Send SMS API v1

📘

API Endpoints & Postman Collection

The SMS channel is supported via Send SMS API v1, Send Message API v2, and Send Message API v1. Refer to this page for information on which API is best suited for your use case.

The API endpoint for Send SMS API v1 is: [https://api.{YourRegion}.webexconnect.io/v1/sms/messages].

Please modify YourRegion in the URL as per your tenant’s region. See Know your endpoint page.

Refer to our Postman Collection here for trying Send SMS API v1.

Authentication

Refer to this page for information on API Authentication.

📘

API Response and Error Codes

SMS API v1 is an asynchronous API. The HTTP response confirming acceptance of your request is sent as soon as you invoke the API. However, the subsequent request processing details are notified via the callback URL i.e., notify URL mentioned in your API request. Refer to this page for more information.

Request Body to Send SMS Using Send SMS API v1

{
    "from": "12233XXXXXX", //Mandatory. Country code with phone number but without '+' sign, or the short code/sender ID.
    "to": "+1647XXXXXXX", //Mandatory. E.164 format required/recommended.
    "content": "SMS- $(sms_parameter1) API v1- $(sms_parameter2)", //Mandatory. 
    "contentType": "text", //Mandatory. 
    "substitutions": { //Optional.
        "{{sms_parameter1}}": "{{sms_value1}}",
        "{{sms_parameter2}}": "{{sms_value2}}"
    },
    "dltTemplateId": "", //Specifies the DLT template ID used for this message. This is applicable only for India.
    "shortenUrls": true, // Boolean. When enabled, this shortens any https links found in the body the message request.
    "shortUrlDomain": "https://www.domain.tld", //Domain configured for shortening the links. Needs to be configured through Support team.
    "trackShortUrlClicks": true, // Boolean. When shortenUrls is true, you can receive CLICKED receipts on your notifyUrl if trackShortUrlClicks is true. 
    "expireAt": "{{TimeinUTC}}",
    "correlationId": "", //Optional. The CorrelationID is a unique identifier that you can attach to every request as a reference a particular transaction or event. This is configured as a part of the request.
    "callbackUrl": "", //Optional. Callback URL for getting notified about the request status.
    "callbackData": "" //Optional. Data that you have configured to receive on the callback Url. This is configured as a part of the request.
    
}

Send SMS API v1 Body Parameters

Sample Response Body

{
    "acceptedTime": "2024-09-04T06:42:16.520-04:00",
    "messageId": "acc27bb5-1234-120x-xx23-1a6036fcced5",
    "correlationId": "1234"
}

{
    "code": "7004",
    "message": "Invalid parameter -  : contentType"
}

{
    "code": "7001",
    "message": "Authentication failed."
}

Steps for configuring branded / short URLs for ShortenLinks capability:

• Work with your IT team to procure the short URL you want to use.
• Add a CNAME record with relevant redirection based on your Webex Connect tenant location (table below).
• If you need HTTPS redirection (highly recommended), reach out to Webex Connect customer support team and provide the domain certificate to add to the Certificate Manager (ACM) for this purpose. This typically requires some lead time hence we recommend you to plan ahead of time for getting this set-up done and leave some time for end-to-end testing.
• Once the backend set-up has been completed by Webex Connect team, you will be notified over email post which you can start using this.

📘

Note

Please note that usage of short domains for SMS links can have an impact on deliverability in some cases. Operators and aggregators implement various firewalls and fraud mitigation services in order to protect customers from fraud. This means URL shortening techniques can sometimes be blocked with no warning, particularly if the words around them seem fraudulent or related to a popular brand or financial entities.