Send SMS description

Please refer to the detailed API endpoint specification: Send SMS

Purpose

The Send SMS API enables agents to send SMS messages using either a custom message body or a predefined SMS template.

Prerequisites

SMS must be enabled for your contact center
The agent must have an extension configured
The Display SMS functionality in WebRTC feature must be enabled for the agent's security access group
You must have access to your contact center API key
A Sender ID must be configured and allowed in your contact center

Request Options

You can send an SMS in one of two ways:

1. Send a custom SMS

Use the body parameter to send a message with custom content.

2. Send a template-based SMS

Use the template object with id and params to populate placeholders in a predefined canned message.

Note: Only one of body or template must be present in a request.

Parameters

Parameter	Description	Type	Required	Notes
agent	The agent's contact center phone extension	string	Yes
number	The SMS recipient's phone number in E.164 format (no `+` sign)	string	Yes
body	The custom SMS message body (1–1600 chars)	string	Yes*	Required if `template` is not used
sender_id	The originating phone number shown to the recipient	string	No
crm	The name of an external CRM or application	string	No
account_id	Contact's CRM identifier	string	No	Used in conjunction with `crm`
template.id	ID of the canned message template	integer	Yes*	Required if `body` is not used
template.params	Key-value pairs to populate template placeholders	object	Yes*	Keys must match template placeholders

Request Examples

Send a custom SMS

{
  "agent": "2003",
  "number": "155555564242",
  "body": "Check out our latest offer!",
  "sender_id": "15554009188"
}

Send a template-based SMS

{
  "agent": "5151",
  "number": "18885658889",
  "template": {
    "id": 174,
    "params": {
      "contact_name": "Tony",
      "agent_name": "John"
    }
  }
}

Response

The following table describes the elements of the response.

Element	Description	Type	Notes
sms_id	UUID of the interaction stored in the Call Detail Record	string	Use this ID to retrieve details using the List CDRs API
segments	Number of message segments (applies to free-text messages)	number	Automatically calculated based on `body` length

Response Sample

{
  "sms_id": "ab52fd83-770c-4069-aaee-x951139x9xf6",
  "segments": 1
}

Troubleshooting

Error Message	Description
Invalid key	Check your contact center API key
Invalid agent extension	Make sure the extension exists and is assigned to an agent
SenderID is not available	Ensure you have a configured Sender ID in your contact center
Invalid destination number	Must be in E.164 format (no `+` sign)
SMS body length must be 1-1600 chars	Applies to free-text messages only
The request must include a valid `template_id`...	When using a template, `template.id` is required
The provided `template_params` do not match placeholders	Check that your `params` match the template's placeholders exactly
SMS is not allowed / disabled for agent / rate limit etc.	General SMS restrictions or agent-level permissions