Send SMS description

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.

ParameterDescriptionTypeRequiredNotes
agentThe agent's contact center phone extension.stringRequiredIt tells Voiso who should receive the interaction.
numberThe SMS recipient's phone number.stringRequiredThe number must be specified in E.164 format without the preceding '+'. For example: 447414992548
bodyThe SMS message.stringRequiredIt 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_idThe originating phone number displayed to the recipient.stringOptionalFor your contact center to send SMS, you must have at least one Sender ID configured.
CRMThe name of an external application, such as a CRM, where contact information is managed.stringOptionalOnce 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_idAn identifier assigned to the contact in an external application such as a CRM.stringOptional

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.

ElementDescriptionTypeNotes
sms_idThe UUID of the interaction stored in the Call Details Record.stringYou can use this ID to get information about the call using the Get CDR API.
segmentsThe number of segments the message body was divided into.numberThe 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.