Send SMS API

API type: POST

URL: https://api.webexinteract.com/v1/sms

Parameters

Here is the list of supported parameters for your API request:

Parameter name	Type	Mandatory	Description
message_body	string	Yes	The content of the SMS message, including any merge fields (${firstname}, ${city} etc.) for personalization. Note: Unicode characters will be auto-detected and charged accordingly: 70 characters per SMS for a single message, and 63 characters per SMS for multiple messages.
template_id	string	Yes	ID of template created from templates page in UI. Content will be populated while sending. Note: Only one of message_body or template_id parameters should be present in the request.
from	string	Yes	Sender ID for the SMS message. Note: Sendernames must be created from the UI before being used in API. You can also buy a long number to send messages here.
to	array of objects	Yes	An array of destination JSON objects that contain the mandatory destination phone numbers, optional personalised merge fields, and correlation_id for each object.
	string	optional	correlation_id : Unique identifier for tracking the request.
	array of strings	Yes	phone: Array of phone numbers of the recipients in E.164 format. Limit to 10000 numbers per request. E.g.,+447741632543
	object	optional	merge_fields values to replace in messagebody for individual recipients in the corresponding "phone" array. Takes precedence over global_merge_fields that can be specified for entire request. Note: Including merge fields will affect the length and cost of the messages._
send_at	date and time	optional	Schedule messages for a future date/time within 7 days. Must be in ISO 8601 format (yyyy-mm-dd'T'hh:mm:ss). Note: If send_at is not specified, the messages will be sent out immediately after the request is accepted.
valid_until	date and time	optional	The validity period for your message. Messages will not be delivered after this date time. Must be in ISO 8601 format (yyyy-mm-dd'T'hh:mm:ss) and within 3 days from send time.
global_merge_fields	object	optional	Global merge fields are applied across all recipients in the request. Note: The to/merge_field value takes priority when a variable is specified in both (to/merge_fields) and (global_merge_fields).

Sample request

{
    "message_body": "Hello ${firstname},/nyour ${count} service is due by ${date}. Contact us on ${phone} to schedule an appointment.",
  //"template_id":"stp_2alB8n4k3BuCjOumRddxXiaA97M", //only one of message_body or template_id should be present
    "send_at": "2025-01-18T02:20:20Z",
    "valid_until": "2025-01-18T22:22:22Z",
    "from": "WxInteract",
    "to": [
        {
            "correlation_id": "corr_id_1",
            "phone": [
                "+4474512XXXXX",
                "+919999999999"
            ],
            "merge_fields": {
                "count": "first",
                "date": "15th Jan, 2025"
            }
        },
        {
            "correlation_id": "corr_id_2",
            "phone": [
                "+4474532XXXXX"
            ],
            "merge_fields": {
                "firstname": "Mark",
                "count": "second",
                "date": "20th Jan, 2025"
            }
        }
    ],
    "global_merge_fields": {
        "firstname": "user",
        "phone": "+447709873XXX"
    }
}

Sample responses

{
    "request_id": "aps_2rLDt24N3TpQklpvfI6qN9rwHa0",
    "messages": [
        {
            "transaction_id": "tid_2rLDt3fdNu76JJPgsXWqn3OKxhU",
            "to": "+4477416XXXXX",
            "status": "queued",
            "code": 1001
        },
        {
            "transaction_id": "tid_2rLDt0d3ulmMWi9wNtFdveMv5fR",
            "to": "+44756810XXXX",
            "status": "queued",
            "code": 1001
        },
        {
            "transaction_id": "tid_2rLDt61fNndzGYqg4N6LZEQQalO",
            "to": "+44756811XXXX",
            "status": "queued",
            "code": 1001
        }
    ],
    "errors": []
}

{
    "request_id": "aps_2rLKYdhLyWHcWWfmVEQrskgn0vi",
    "messages": [
        {
            "transaction_id": "tid_2rLKYZUnrY4OavlcuhKaGjPSbRs",
            "to": "+44756810XXX4",
            "status": "queued",
            "code": 1001
        }
    ],
    "errors": [
        {
            "to": "+4477416325434477416325434",
            "status": "error",
            "code": 1002,
            "message": "Invalid phone number or unsupported region."
        }
    ]
}

{
    "errors": [
        {
            "field": "message_body, template_id",
            "message": "neither message_body nor template_id was provided",
            "code": 10006
        }
    ]
}

{
    "errors": [
        {
            "field": "to[0].phone",
            "message": "invalid recipients object format, no phone numbers provided.",
            "code": 10006
        }
    ]
}

{
    "errors": [
        {
            "field": "message_body, template_id",
            "message": "neither message_body nor template_id was provided",
            "code": 10006
        }
    ]
}

{
    "errors": [
        {
            "field": "send_at",
            "message": "date must be in the future",
            "code": 10006
        }
    ]
}

{
    "errors": [
        {
            "field": "send_at",
            "message": "date cannot be more than 7 days in the future",
            "code": 10006
        }
    ]
}

{
    "errors": [
        {
            "field": "valid_until",
            "message": "date cannot be more than 3 days in the future",
            "code": 10006
        }
    ]
}

{
    "errors": [
        {
            "field": "message_body, template_id",
            "message": "both were provided, only one is allowed.",
            "code": 10006
        }
    ]
}

{
    "errors": [
        {
            "field": "valid_until",
            "message": "date must be in the future when compared to send_at ",
            "code": 10006
        }
    ]
}