ℹ️
Testing your integration
To test your integration you can call the test endpoint (see below). Use this endpoint to verify your integration without sending a message or affecting your balance.

Send an SMS message

Method: POST

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

Use

Send a template or message content specified in your request to a set of phone numbers.

Parameters

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.
	string	optional	country_code: 2 char country code (e.g., GB, ES). If present, any non E1.64 numbers in phone array will be converted to the given country code.
	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._
schedule_at	date and time	optional	Schedule messages for a future date/time within 390 days. Must be in ISO 8601 format (yyyy-mm-dd'T'hh:mm:ss). Note: If scheduled_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).
skip_optout_check	boolean	optional	When set to "true", bypasses the opt-out check and messages will be sent to contacts who have opted out.

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
    "schedule_at": "2025-01-18T02:20:20Z",
    "valid_until": "2025-01-18T22:22:22Z",
    "from": "WxInteract",
    "skip_optout_check" : true,
    "to": [
        {
            "correlation_id": "corr_id_1",
            "phone": [
                "+4474512XXXXX",
                "+919999999999"
            ],
            "merge_fields": {
                "count": "first",
                "date": "15th Jan, 2025"
            }
        },
        {
            "correlation_id": "corr_id_2",
            "country_code": "GB"
						"phone": [
                "074532XXXXX"
            ],
            "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 or invalid phone number for country code."
        }
    ]
}

{
    "errors": [
        {
            "message": "insufficient balance",
            "code": 10005
        }
    ]
}

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

{
  "trace_id": "af04xe461e8ede75",
  "errors": [
    {
      "field": "from",
      "message": "no 'from' was provided",
      "code": 10006
    }
  ]
}

{
    "trace_id": "5de7aa3ada89c7a9",
    "errors": [
        {
            "field": "schedule_at",
            "message": "date must be in the future",
            "code": 10006
        }
    ]
}

{
    "trace_id": "b9dd924e3320b46d",
    "errors": [
        {
            "field": "schedule_at",
            "message": "date cannot be more than 390 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
        }
    ]
}

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

Test your SMS API integration

Method: POST

Endpoint: https://api.webexinteract.com/v1/sms/test

Use

Use this endpoint to verify your integration without sending a message or affecting your balance.

Please note that while a 200 response indicates a valid request, no transactions will have been created. Records will not appear in any reports.

Parameters

This endpoint accepts the same parameters as the standard SMS API endpoint. See SMS endpoint above for details.

Sample request

See SMS endpoint above for details.

Sample responses

[
  {
    "request_id": "aps_34gwaass6GrNQZWosCYunS7Dw3j",
    "messages": [
      {
        "transaction_id": null,
        "to": "+447700900001",
        "status": "validated",
        "code": 1003
      }
    ],
    "errors": []
  },
  {
    "request_id": "aps_1abcdefgH2IjklMnOpQrStUvWxYz",
    "messages": [
      {
        "transaction_id": null,
        "to": "+447700900002",
        "status": "validated",
        "code": 1003
      }
    ],
    "errors": []
  },
  {
    "request_id": "aps_9xYzWvU7tSrQpOnMlKjIhGfEdCbA",
    "messages": [
      {
        "transaction_id": null,
        "to": "+447700900003",
        "status": "validated",
        "code": 1003
      }
    ],
    "errors": []
  }

{
  "request_id": "aps_34h3h0rtc1UEtusUam5iMf76Lof",
  "messages": [
    {
      "transaction_id": null,
      "to": "+447800000001",
      "status": "validated",
      "code": 1003
    }
  ],
  "errors": [
    {
      "to": "+447700900002",
      "status": "error",
      "code": 1002,
      "message": "Invalid phone number or unsupported region or invalid phone number for country code."
    },
    {
      "to": "+447700900003",
      "status": "error",
      "code": 1002,
      "message": "Invalid phone number or unsupported region or invalid phone number for country code."
    }
  ]
}

{
  "trace_id": "c442zzb402b1b6c7",
  "errors": [
    {
      "field": null,
      "message": "insufficient balance.",
      "code": 10005
    }
  ]
}

Error Codes

Code	Field	Message
10001*	N/A	queued
10003**	N/A	validated
10005	N/A	insufficient balance
10006	message_body, template_id	neither message_body nor template_id was provided
10006	message_body, template_id	both were provided, only one is allowed.
10006	to[0].phone	invalid recipients object format, no phone numbers provided.
10006	from	no 'from' was provided
10006	schedule_at	date must be in the future
10006	schedule_at	date cannot be more than 390 days in the future
10006	schedule_at	date cannot be more than 3 days in the future
10006	valid_until	Invalid or malformed request body
10006	valid_until	date must be in the future when compared to send_at

*Returned on sms endpoint only

**Returned on sms/test endpoint only

Send SMS API

ℹ️
Testing your integration

Send an SMS message

Method: POST

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

Use

Parameters

Sample request

Sample responses

Test your SMS API integration

Method: POST

Endpoint: https://api.webexinteract.com/v1/sms/test

Use

Parameters

Sample request

Sample responses

Error Codes

ℹ️Testing your integration

Send an SMS message

Method: POST

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

Use

Parameters

Sample request

Sample responses

Test your SMS API integration

Method: POST

Endpoint: https://api.webexinteract.com/v1/sms/test

Use

Parameters

Sample request

Sample responses

Error Codes

ℹ️
Testing your integration