Initiate WhatsApp

curl --request POST \
  --url https://api.agents.timepay.ai/api/v1/initiate/{campaignId}/whatsapp \
  --header 'Authorization: <authorization>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "templateId": "<string>",
  "conversationSettings": {
    "agentId": "<string>",
    "dispositionId": "<string>"
  },
  "limit": 123,
  "filters": {
    "ids": [
      "<string>"
    ],
    "exclude_ids": [
      "<string>"
    ],
    "payment_status": [
      "<string>"
    ],
    "language": [
      "<string>"
    ],
    "custom": {}
  }
}
'

import requests

url = "https://api.agents.timepay.ai/api/v1/initiate/{campaignId}/whatsapp"

payload = {
    "templateId": "<string>",
    "conversationSettings": {
        "agentId": "<string>",
        "dispositionId": "<string>"
    },
    "limit": 123,
    "filters": {
        "ids": ["<string>"],
        "exclude_ids": ["<string>"],
        "payment_status": ["<string>"],
        "language": ["<string>"],
        "custom": {}
    }
}
headers = {
    "Authorization": "<authorization>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

const options = {
  method: 'POST',
  headers: {Authorization: '<authorization>', 'Content-Type': 'application/json'},
  body: JSON.stringify({
    templateId: '<string>',
    conversationSettings: {agentId: '<string>', dispositionId: '<string>'},
    limit: 123,
    filters: {
      ids: ['<string>'],
      exclude_ids: ['<string>'],
      payment_status: ['<string>'],
      language: ['<string>'],
      custom: {}
    }
  })
};

fetch('https://api.agents.timepay.ai/api/v1/initiate/{campaignId}/whatsapp', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api.agents.timepay.ai/api/v1/initiate/{campaignId}/whatsapp",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => json_encode([
    'templateId' => '<string>',
    'conversationSettings' => [
        'agentId' => '<string>',
        'dispositionId' => '<string>'
    ],
    'limit' => 123,
    'filters' => [
        'ids' => [
                '<string>'
        ],
        'exclude_ids' => [
                '<string>'
        ],
        'payment_status' => [
                '<string>'
        ],
        'language' => [
                '<string>'
        ],
        'custom' => [
                
        ]
    ]
  ]),
  CURLOPT_HTTPHEADER => [
    "Authorization: <authorization>",
    "Content-Type: application/json"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://api.agents.timepay.ai/api/v1/initiate/{campaignId}/whatsapp"

	payload := strings.NewReader("{\n  \"templateId\": \"<string>\",\n  \"conversationSettings\": {\n    \"agentId\": \"<string>\",\n    \"dispositionId\": \"<string>\"\n  },\n  \"limit\": 123,\n  \"filters\": {\n    \"ids\": [\n      \"<string>\"\n    ],\n    \"exclude_ids\": [\n      \"<string>\"\n    ],\n    \"payment_status\": [\n      \"<string>\"\n    ],\n    \"language\": [\n      \"<string>\"\n    ],\n    \"custom\": {}\n  }\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("Authorization", "<authorization>")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.post("https://api.agents.timepay.ai/api/v1/initiate/{campaignId}/whatsapp")
  .header("Authorization", "<authorization>")
  .header("Content-Type", "application/json")
  .body("{\n  \"templateId\": \"<string>\",\n  \"conversationSettings\": {\n    \"agentId\": \"<string>\",\n    \"dispositionId\": \"<string>\"\n  },\n  \"limit\": 123,\n  \"filters\": {\n    \"ids\": [\n      \"<string>\"\n    ],\n    \"exclude_ids\": [\n      \"<string>\"\n    ],\n    \"payment_status\": [\n      \"<string>\"\n    ],\n    \"language\": [\n      \"<string>\"\n    ],\n    \"custom\": {}\n  }\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://api.agents.timepay.ai/api/v1/initiate/{campaignId}/whatsapp")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["Authorization"] = '<authorization>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"templateId\": \"<string>\",\n  \"conversationSettings\": {\n    \"agentId\": \"<string>\",\n    \"dispositionId\": \"<string>\"\n  },\n  \"limit\": 123,\n  \"filters\": {\n    \"ids\": [\n      \"<string>\"\n    ],\n    \"exclude_ids\": [\n      \"<string>\"\n    ],\n    \"payment_status\": [\n      \"<string>\"\n    ],\n    \"language\": [\n      \"<string>\"\n    ],\n    \"custom\": {}\n  }\n}"

response = http.request(request)
puts response.read_body

{
  "success": true,
  "message": "WhatsApp messages initiated for 250 customers",
  "results": {
    "totalMatched": 500,
    "customersSelected": 250,
    "initiated": 250,
    "failed": 0,
    "batchesProcessed": 1,
    "errors": []
  }
}

{
  "success": false,
  "message": "WhatsApp messages initiated for 200 of 250 customers",
  "results": {
    "totalMatched": 500,
    "customersSelected": 250,
    "initiated": 200,
    "failed": 50,
    "batchesProcessed": 1,
    "errors": [
      {
        "batch": 1,
        "error": "Initiation failed",
        "reason": "Workflow runner timeout",
        "affectedCustomers": 50
      }
    ]
  }
}

{
  "success": false,
  "message": "Validation failed",
  "errors": [
    "templateId is required"
  ]
}

{
  "success": false,
  "message": "Campaign not found"
}

{
  "success": false,
  "message": "No customers found matching the given filters"
}

{
  "success": false,
  "error": "Internal Server Error",
  "message": "An unexpected error occurred"
}

Initiate WhatsApp

curl --request POST \
  --url https://api.agents.timepay.ai/api/v1/initiate/{campaignId}/whatsapp \
  --header 'Authorization: <authorization>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "templateId": "<string>",
  "conversationSettings": {
    "agentId": "<string>",
    "dispositionId": "<string>"
  },
  "limit": 123,
  "filters": {
    "ids": [
      "<string>"
    ],
    "exclude_ids": [
      "<string>"
    ],
    "payment_status": [
      "<string>"
    ],
    "language": [
      "<string>"
    ],
    "custom": {}
  }
}
'

import requests

url = "https://api.agents.timepay.ai/api/v1/initiate/{campaignId}/whatsapp"

payload = {
    "templateId": "<string>",
    "conversationSettings": {
        "agentId": "<string>",
        "dispositionId": "<string>"
    },
    "limit": 123,
    "filters": {
        "ids": ["<string>"],
        "exclude_ids": ["<string>"],
        "payment_status": ["<string>"],
        "language": ["<string>"],
        "custom": {}
    }
}
headers = {
    "Authorization": "<authorization>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

const options = {
  method: 'POST',
  headers: {Authorization: '<authorization>', 'Content-Type': 'application/json'},
  body: JSON.stringify({
    templateId: '<string>',
    conversationSettings: {agentId: '<string>', dispositionId: '<string>'},
    limit: 123,
    filters: {
      ids: ['<string>'],
      exclude_ids: ['<string>'],
      payment_status: ['<string>'],
      language: ['<string>'],
      custom: {}
    }
  })
};

fetch('https://api.agents.timepay.ai/api/v1/initiate/{campaignId}/whatsapp', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api.agents.timepay.ai/api/v1/initiate/{campaignId}/whatsapp",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => json_encode([
    'templateId' => '<string>',
    'conversationSettings' => [
        'agentId' => '<string>',
        'dispositionId' => '<string>'
    ],
    'limit' => 123,
    'filters' => [
        'ids' => [
                '<string>'
        ],
        'exclude_ids' => [
                '<string>'
        ],
        'payment_status' => [
                '<string>'
        ],
        'language' => [
                '<string>'
        ],
        'custom' => [
                
        ]
    ]
  ]),
  CURLOPT_HTTPHEADER => [
    "Authorization: <authorization>",
    "Content-Type: application/json"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://api.agents.timepay.ai/api/v1/initiate/{campaignId}/whatsapp"

	payload := strings.NewReader("{\n  \"templateId\": \"<string>\",\n  \"conversationSettings\": {\n    \"agentId\": \"<string>\",\n    \"dispositionId\": \"<string>\"\n  },\n  \"limit\": 123,\n  \"filters\": {\n    \"ids\": [\n      \"<string>\"\n    ],\n    \"exclude_ids\": [\n      \"<string>\"\n    ],\n    \"payment_status\": [\n      \"<string>\"\n    ],\n    \"language\": [\n      \"<string>\"\n    ],\n    \"custom\": {}\n  }\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("Authorization", "<authorization>")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.post("https://api.agents.timepay.ai/api/v1/initiate/{campaignId}/whatsapp")
  .header("Authorization", "<authorization>")
  .header("Content-Type", "application/json")
  .body("{\n  \"templateId\": \"<string>\",\n  \"conversationSettings\": {\n    \"agentId\": \"<string>\",\n    \"dispositionId\": \"<string>\"\n  },\n  \"limit\": 123,\n  \"filters\": {\n    \"ids\": [\n      \"<string>\"\n    ],\n    \"exclude_ids\": [\n      \"<string>\"\n    ],\n    \"payment_status\": [\n      \"<string>\"\n    ],\n    \"language\": [\n      \"<string>\"\n    ],\n    \"custom\": {}\n  }\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://api.agents.timepay.ai/api/v1/initiate/{campaignId}/whatsapp")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["Authorization"] = '<authorization>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"templateId\": \"<string>\",\n  \"conversationSettings\": {\n    \"agentId\": \"<string>\",\n    \"dispositionId\": \"<string>\"\n  },\n  \"limit\": 123,\n  \"filters\": {\n    \"ids\": [\n      \"<string>\"\n    ],\n    \"exclude_ids\": [\n      \"<string>\"\n    ],\n    \"payment_status\": [\n      \"<string>\"\n    ],\n    \"language\": [\n      \"<string>\"\n    ],\n    \"custom\": {}\n  }\n}"

response = http.request(request)
puts response.read_body

{
  "success": true,
  "message": "WhatsApp messages initiated for 250 customers",
  "results": {
    "totalMatched": 500,
    "customersSelected": 250,
    "initiated": 250,
    "failed": 0,
    "batchesProcessed": 1,
    "errors": []
  }
}

{
  "success": false,
  "message": "WhatsApp messages initiated for 200 of 250 customers",
  "results": {
    "totalMatched": 500,
    "customersSelected": 250,
    "initiated": 200,
    "failed": 50,
    "batchesProcessed": 1,
    "errors": [
      {
        "batch": 1,
        "error": "Initiation failed",
        "reason": "Workflow runner timeout",
        "affectedCustomers": 50
      }
    ]
  }
}

{
  "success": false,
  "message": "Validation failed",
  "errors": [
    "templateId is required"
  ]
}

{
  "success": false,
  "message": "Campaign not found"
}

{
  "success": false,
  "message": "No customers found matching the given filters"
}

{
  "success": false,
  "error": "Internal Server Error",
  "message": "An unexpected error occurred"
}

Headers

string

required

Bearer token for authentication (e.g., Bearer <your_token>).

Path Parameters

string

required

The campaign ID containing the customers to message.

Body Parameters

string

required

The ID of the WhatsApp template to be sent.

object

Optional configuration for conversational settings. If present, both agentId and dispositionId are required.

Show properties

string

required

AI agent ID to handle the conversations.

string

required

Disposition ID for conversation categorization.

integer

Maximum number of customers to message. If omitted, all matching customers are messaged.

object

Optional filters to target specific customers. If omitted, all customers in the campaign are messaged. Multiple filters are combined with AND logic.

Show filter properties

string[]

Message only these specific customer IDs (loan_id or lead_id).

string[]

Exclude these customer IDs from messaging.

string[]

Filter by payment status. Accepts a single value or an array.

Show options

bounced — Payment was attempted but failed.
pending — Payment is due but not yet initiated.
partial — Customer has made a partial payment.
paid — Payment has been completed.
received — Payment has been received and confirmed.

string[]

Filter by customer language preference. Accepts a single value or an array (e.g., "hindi" or ["hindi", "english"]).

object

Custom field exact-match filters as key-value pairs. Values can be a single string or an array of strings.

Example

      {
        "branch": "mumbai",
        "product_type": ["personal_loan", "home_loan"]
      }

Response

boolean

true if all messages were initiated successfully, false otherwise.

string

Summary of the operation result.

object

Detailed breakdown of the message initiation.

Show properties

integer

Total customers matching the query/filters in the campaign.

integer

Customers selected for messaging (respects limit if provided).

integer

Messages successfully initiated.

integer

Messages that failed to initiate.

integer

Number of message batches processed.

array

Array of error objects for failed batches.

Show error object

integer

Batch number that failed.

string

Error type.

string

Human-readable error reason.

integer

Number of customers affected in the failed batch.

Response Status Codes:

200 — All messages initiated successfully
207 — Partial success (some messages initiated, some failed)
400 — Validation error
404 — Campaign or customers not found
500 — All messages failed or internal server error

{
  "success": true,
  "message": "WhatsApp messages initiated for 250 customers",
  "results": {
    "totalMatched": 500,
    "customersSelected": 250,
    "initiated": 250,
    "failed": 0,
    "batchesProcessed": 1,
    "errors": []
  }
}

{
  "success": false,
  "message": "WhatsApp messages initiated for 200 of 250 customers",
  "results": {
    "totalMatched": 500,
    "customersSelected": 250,
    "initiated": 200,
    "failed": 50,
    "batchesProcessed": 1,
    "errors": [
      {
        "batch": 1,
        "error": "Initiation failed",
        "reason": "Workflow runner timeout",
        "affectedCustomers": 50
      }
    ]
  }
}

{
  "success": false,
  "message": "Validation failed",
  "errors": [
    "templateId is required"
  ]
}

{
  "success": false,
  "message": "Campaign not found"
}

{
  "success": false,
  "message": "No customers found matching the given filters"
}

{
  "success": false,
  "error": "Internal Server Error",
  "message": "An unexpected error occurred"
}

Usage Examples

Message all customers in a campaign:

{
  "templateId": "hfu7VL6sBhI6NPm"
}

Message specific customers with conversation settings:

{
  "conversationSettings": {
    "agentId": "PPTnLQAvGlLtVgRbpcFn",
    "dispositionId": "XaYnpMfmTumXNSgOSIZB"
  },
  "templateId": "hfu7VL6sBhI6NPm",
  "filters": {
    "ids": ["LOANID-2043153", "LOANID-2043154"]
  }
}

Message bounced and pending customers:

{
  "templateId": "hfu7VL6sBhI6NPm",
  "filters": {
    "payment_status": ["bounced", "pending"]
  }
}

Message all customers except specific ones:

{
  "templateId": "hfu7VL6sBhI6NPm",
  "filters": {
    "exclude_ids": ["LOANID-2043153", "LOANID-2043154"]
  }
}

​Headers

​Path Parameters

​Body Parameters

​Response

​Usage Examples

Headers

Path Parameters

Body Parameters

Response

Usage Examples