Use the Send SMS API to enable external applications to send SMS through Voiso. For example, you can use it to allow agents to send an SMS from your CRM.
Please refer to the detailed API endpoint specification: Send SMS
Limitations:
- The send SMS API does not currently allow you to send bulk SMS.
- You can send up to 20 SMS messages to a specific number per calendar day per agent to the same recipient, according to the time zone of the contact center.
- You can send no more than 1 SMS every 2 seconds if the sender ID, recipient number, agent extension, and text message are identical. There is no limit to the number of SMS if only the recipient numbers differ, even if the other parameters remain the same.
- SMS text length: 1–1600 characters.
- Links in SMS messages might be restricted for your contact center.
Prerequisites
- SMS must be enabled for your contact center
- The agent must have an extension configured. The Agent is identified using the extension parameter in the request.
- 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.
- You must have a Sender ID configured.
- The Sender ID must be on the allowed list of your contact center.
Making requests
Note: The Send SMS API uses a POST request. Request and response payloads are formatted as JSON, using UTF-8 encoding and URL-encoded values.
Authentication
The Send SMS API requires the Base URL (cluster_id) and the contact center API key.
Request parameters
The send SMS API uses the following parameters.
Parameter | Description | Type | Required | Notes |
---|---|---|---|---|
agent | The agent's contact center phone extension. | string | Required | It tells Voiso who should receive the interaction. |
number | The SMS recipient's phone number. | string | Required | The number must be specified in E.164 format without the preceding '+'. For example: 447414992548 |
body | The SMS message. | string | Required | It must be between 1 and 1600 characters in length, with a limit of 160 characters for a single SMS. Voiso divides longer messages into segments and delivers them as multiple messages. |
sender_id | The originating phone number displayed to the recipient. | string | Optional | For your contact center to send SMS, you must have at least one Sender ID configured. |
CRM | The name of an external application, such as a CRM, where contact information is managed. | string | Optional | Once you specify the crm parameter, the corresponding interactions will be flagged with this parameter in the logs (CDR). This can be useful for reporting and debugging purposes. |
account_id | An identifier assigned to the contact in an external application such as a CRM. | string | Optional |
With these required parameters, you can make a simple request:
{
"method": "POST",
"url": "https://cluster1.voiso.com/api/v1/cc7c96b89...fb89b00ab6c3/sendsms",
"params": {
"agent": "2003",
"number": "155555564242",
"body": "Check out our latest offer!",
"sender_id": "15554009188"
}
}
To make more advanced requests, you can include optional parameters. Here is an example of a complete request:
{
"method": "POST",
"url": "https://cluster1.voiso.com/api/v1/cc7c96b89...fb89b00ab6c3/sendsms",
"params": {
"agent": "2003",
"number": "155555564242",
"body": "Check out our latest offer!",
"sender_id": "15554009188"
"CRM": "Salesforce",
"account_id": "3MVG9fe4g9fhX0E7U2AC"
}
}
Response
If the SMS is successful, the API responds with the interaction's UUID. You can use this ID to get information about the interaction using the Get CDR API.
The following table describes the elements of the response.
Element | Description | Type | Notes |
---|---|---|---|
sms_id | The UUID of the interaction stored in the Call Details Record. | string | You can use this ID to get information about the call using the Get CDR API. |
segments | The number of segments the message body was divided into. | number | The message body must be between 1 and 1600 characters in length, with a limit of 160 characters for a single SMS. Voiso divides longer messages into segments and delivers them as multiple messages. |
Response sample
{
"sms_id": "ab52fd83-770c-4069-aaee-x951139x9xf6",
"segments": 1
}
Troubleshooting
The following issues are sometimes encountered:
Invalid key
The send SMS API requires the contact center API key to validate the request. If you see this error, "error": "Invalid key"
, check that you use the correct contact center API key. For more information about API keys, refer to Authentication.
Invalid agent extension
If you see this error, "error": "Invalid agent extension"
, the extension specified is either in the wrong format or is not assigned to any agent. Ensure the agent's extension is correctly formatted.
SenderID is not available
If you see this error "error": "SenderID is not available"
, the Sender ID specified is either in the wrong format or does not exist. Ensure you have a valid Sender ID configured for your contact center, and that it is specified correctly.
Invalid destination number
If you see this error, "error": "Invalid destination number"
, it means that the outbound phone number is not in E.164 format or the number does not exist. Verify the phone number is correct and in the correct format, without the preceding '+'. For example: 4407414992548.
SMS body length must be 1-1600 chars
If you see this error, "error": "SMS body length must be 1-1600 chars"
, it means that the message is either blank or is more than 1600 characters in length. Either add a message body or edit it to fit the character limit.