Skip to main content
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": {}
  }
}
'
{
  "success": true,
  "message": "WhatsApp messages initiated for 250 customers",
  "results": {
    "totalMatched": 500,
    "customersSelected": 250,
    "initiated": 250,
    "failed": 0,
    "batchesProcessed": 1,
    "errors": []
  }
}

​
Headers

​
Authorization
string
required
Bearer token for authentication (e.g., Bearer <your_token>).

​
Path Parameters

​
campaignId
string
required
The campaign ID containing the customers to message.

​
Body Parameters

​
templateId
string
required
The ID of the WhatsApp template to be sent.
​
conversationSettings
object
Optional configuration for conversational settings. If present, both agentId and dispositionId are required.
​
limit
integer
Maximum number of customers to message. If omitted, all matching customers are messaged.
​
filters
object
Optional filters to target specific customers. If omitted, all customers in the campaign are messaged. Multiple filters are combined with AND logic.

​
Response

​
success
boolean
true if all messages were initiated successfully, false otherwise.
​
message
string
Summary of the operation result.
​
results
object
Detailed breakdown of the message initiation.
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": []
  }
}

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