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, 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. This must be a string containing a valid e.164 phone number without the '+'.
• 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
• user_id
  The ID of the user the SMS is sent on behalf of. The SMS then shows this user as its agent in CDRs. The user must be a current user of your contact center with the Send SMS and view SMS history permission. To find a user's ID from their extension, use Get list of users with the extension filter.

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
  If you include user_id, the canned message must be shared with at least one of that user's teams.
• message.content_data.params (optional)
  Key value pairs for canned message placeholders.

Related endpoints

• Get a canned message ID: Get list of canned messages
• Get a user ID: Get list of users. This endpoint requires the users.read scope.

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"
        }
      }
    }
  }'

Send an SMS on behalf of a user

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",
    "user_id": 25,
    "message": {
      "content_type": "text",
      "content_data": {
        "body": "Hello, this is your agent following up on your request."
      }
    }
  }'

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.
• If you omit user_id, the SMS is sent without an agent and shows no agent in CDRs.

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.
• user_id is not a current user of your contact center, for example a deleted user or a user of another contact center (errors.user_id: "must exist").
• The user does not have the Send SMS and view SMS history permission (errors.user_id: "must be allowed to send SMS").
• With user_id, the canned message is not shared with any of the user's teams (errors.message.content_data.canned_message_id: "must be shared with a team of the user").

429 Too many requests

What to do:

• Reduce request frequency and retry with backoff.