> ## Documentation Index
> Fetch the complete documentation index at: https://agents.docs.timepay.ai/llms.txt
> Use this file to discover all available pages before exploring further.
# Initiate SMS
> Initiate SMS messages for customers in a campaign with optional filters to target specific subsets.
### Headers
Bearer token for authentication (e.g., `Bearer `).
### Path Parameters
The campaign ID containing the customers to message.
### Body Parameters
The ID of the SMS template to be sent.
Maximum number of customers to message. If omitted, all matching customers are messaged.
Optional filters to target specific customers. If omitted, all customers in the campaign are messaged. Multiple filters are combined with **AND** logic.
Message only these specific customer IDs (`loan_id` or `lead_id`).
Exclude these customer IDs from messaging.
Filter by payment status. Accepts a single value or an array.
* `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.
Filter by customer language preference. Accepts a single value or an array (e.g., `"hindi"` or `["hindi", "english"]`).
Custom field exact-match filters as key-value pairs. Values can be a single string or an array of strings.
```json Example theme={null}
{
"branch": "mumbai",
"product_type": ["personal_loan", "home_loan"]
}
```
### Response
`true` if all messages were initiated successfully, `false` otherwise.
Summary of the operation result.
Detailed breakdown of the message initiation.
Total customers matching the query/filters in the campaign.
Customers selected for messaging (respects `limit` if provided).
Messages successfully initiated.
Messages that failed to initiate.
Number of message batches processed.
Array of error objects for failed batches.
Batch number that failed.
Error type.
Human-readable error reason.
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
```json 200 All Messages Initiated theme={null}
{
"success": true,
"message": "SMS messages initiated for 250 customers",
"results": {
"totalMatched": 500,
"customersSelected": 250,
"initiated": 250,
"failed": 0,
"batchesProcessed": 1,
"errors": []
}
}
```
```json 207 Partial Success theme={null}
{
"success": false,
"message": "SMS 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
}
]
}
}
```
```json 400 Validation Error theme={null}
{
"success": false,
"message": "Validation failed",
"errors": [
"templateId is required"
]
}
```
```json 404 Campaign Not Found theme={null}
{
"success": false,
"message": "Campaign not found"
}
```
```json 404 No Customers Found theme={null}
{
"success": false,
"message": "No customers found matching the given filters"
}
```
```json 500 Server Error theme={null}
{
"success": false,
"error": "Internal Server Error",
"message": "An unexpected error occurred"
}
```
### Usage Examples
**Message all customers in a campaign:**
```json theme={null}
{
"templateId": "hfu7VL6sBhI6NPm"
}
```
**Message specific customers:**
```json theme={null}
{
"templateId": "hfu7VL6sBhI6NPm",
"filters": {
"ids": ["LOANID-2043153", "LOANID-2043154"]
}
}
```
**Message bounced and pending customers:**
```json theme={null}
{
"templateId": "hfu7VL6sBhI6NPm",
"filters": {
"payment_status": ["bounced", "pending"]
}
}
```
**Message all customers except specific ones:**
```json theme={null}
{
"templateId": "hfu7VL6sBhI6NPm",
"filters": {
"exclude_ids": ["LOANID-2043153", "LOANID-2043154"]
}
}
```