What this does

When you send a Send SMS request, Voiso creates an outbound SMS message and returns an sms.id you can store for tracking.

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.