Send SMS overview

The Send SMS endpoint sends an outbound SMS message to a phone number.

Requirements: Base URL, Authentication, Error codes

Scope: messaging.sms.send

What this does

When you send a Send SMS request,

Endpoint

POST /api/v4/messaging/sms

Request body

Required fields:

• phone_number
  The recipient’s phone number.
• message
  The message payload.

Optional fields:

• sender_id
  The originating phone number or text displayed to the recipient. Two string formats are supported, a string of numbers representing an e.164 formatted phone number without the '+' or an alphanumeric string of up to 30 characters in the following format: ^[-Z-z0-9]{1,30}$. The alphanumeric string must be a sender ID assigned to your contact center. For more information, refer to Sender ID Groups.
• source
  Information about the external system that provided the contact number, such as a CRM.
  If you include source, both of the following fields are required:
  • source.system
  • source.account_id

message object

Required fields:

• message.content_type
  One of: text, canned_message
• message.content_data
  Structure depends on content_type:

For content_type: text:

• message.content_data.body

For content_type: canned_message:

• message.content_data.canned_message_id
• message.content_data.params (optional)
  Key value pairs for canned message placeholders.

Related endpoints

• Get a canned message ID: Get list of canned messages

Example requests

Send a text SMS

curl -X POST "https://{cluster_id}.voiso.com/api/v4/messaging/sms" \
  -H "Authorization: Bearer <contact_center_api_key>" \
  -H "Content-Type: application/json" \
  -d '{
    "phone_number": "18885658889",
    "sender_id": "18885658880",
    "message": {
      "content_type": "text",
      "content_data": {
        "body": "Hello, your order has been shipped."
      }
    },
    "source": {
      "system": "zoho",
      "account_id": "123321"
    }
  }'

Send an SMS using a canned message

curl -X POST "https://{cluster_id}.voiso.com/api/v4/messaging/sms" \
  -H "Authorization: Bearer <contact_center_api_key>" \
  -H "Content-Type: application/json" \
  -d '{
    "phone_number": "18885658889",
    "message": {
      "content_type": "canned_message",
      "content_data": {
        "canned_message_id": 174,
        "params": {
          "contact_name": "Tony",
          "agent_name": "John"
        }
      }
    }
  }'

Response

If successful, the API returns an sms object containing the SMS ID.

{
  "sms": {
    "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6"
  }
}

Notes

• Phone numbers in examples are shown without a leading plus sign.
• If you use source, include both system and account_id so the SMS can be associated with your external system.

Troubleshooting

401 Unauthorized

What to check:

• You are sending Authorization: Bearer <contact_center_api_key>.

403 Forbidden

What to check:

• The API key is valid, but does not have access to Messaging resources.

422 Unprocessable Entity

Common causes:

• phone_number is missing or invalid.
• message.content_type is missing or not one of text or canned_message.
• message.content_data does not match the selected content_type.
• source is provided but source.system or source.account_id is missing.

429 Too many requests

What to do:

• Reduce request frequency and retry with backoff.