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

401 Unauthorized

{
  "success": false,
  "error": "Unauthorized",
  "message": "Missing or invalid authorization header"
}

403 Forbidden

{
  "success": false,
  "error": "Forbidden",
  "message": "You don't have the required permission to perform this action"
}

string

required

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

string

Optional. Use this header only when the authenticated user belongs to multiple organizations. It identifies the organization to target for this action.

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"
}

Error Codes

Status	Description
`400`	Validation error
`401`	Unauthorized - missing or invalid authorization header
`403`	Forbidden - insufficient permission to perform this action
`404`	Campaign or matching customers not found
`500`	Internal server error

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

​Error Codes

​Usage Examples

Headers

Path Parameters

Body Parameters

Response

Error Codes

Usage Examples