SMS Messaging API

URI: https://messagingapi.sinch.com/v1

Overview

The SMS messaging API allows you to send SMS messages and check their status using the Sinch dashboard.

ErrorCodes

[Error Codes]
   40001 - Parameter validation
   40002 - Missing parameter
   40003 - Invalid request
   40100 - Illegal authorization header
   40200 - There is not enough funds to send the message
   40300 - Forbidden request
   40301 - Invalid authorization scheme for calling the method
   40303 - No verified phone number on your Sinch account
   40303 - Full Sms access not enabled for App. Can only send Sms to verified numbers.
   50000 - Internal error

Send SMS

[POST] /Sms/{number}

Send an SMS message to the number supplied in the URL, with the contents defined in the body as described below.

Important: To use the Sinch SMS API, you will need to have a verified phone number in the Sinch dashboard. To verify your phone number, sign in to the Sinch dashboard click Quickstart and follow the instructions. Also check the recipient number restrictions.

Authorization

This is a protected resource and requires an application signed request or basic auth.

Request

[Body]
    string? - from
    string - message

from shows the number or alphanumeric that will be shown as sender in the SMS. Check also the “From” field restrictions.

message is the actual message that will be sent in the SMS.

Example - without specifying the sender

URL: [POST] https://messagingapi.sinch.com/v1/sms/+46700000000
body
{
    "message":"Hello there"
}

Example - using a sender number

URL: [POST] https://messagingapi.sinch.com/v1/sms/+46700000000
body
{
    "from":"+46701234567",
    "message":"Hello there"
}

Recipient number restrictions

With a Sandbox app you will only be able to send SMS to your verified phone number.

To send SMS to any phone number, you will need a Production app with “Full SMS access” enabled. To request “Full SMS access” for your Production app, go to the SMS settings of your Production app and request full SMS access.

“From” field restrictions

The “From” field indicates the phone number or alphanumeric string that will be displayed to the recipient of the SMS message. There are a number of restrictions that should be considered when setting the “From” field:

By default, the outgoing SMS message will show the verified phone number from your account as “From” field.

If you have rented an SMS number from the Sinch dashboard, then you can also set this number as sender in the “From” field.

For SMS to the United States, you always need to rent a Sinch SMS number.

To rent an SMS number and use it as the “From” number, please follow these steps:

  1. Rent an SMS number from the Sinch dashboard, under the tab “Numbers”.
  2. Assign the number to your application. Under the “Apps” tab, select your app and assign the number under the app SMS settings.
  3. When calling the SMS API, set the number that you assigned to your app as “From”.
  4. If you want to allow your end users to reply to this number, follow the instructions in the section SMS Messaging Callback API to implement the logic to receive the replies in your backend.

Alternatively, you can rent and configure numbers with REST APIs. For more information please check the Number Administration documentation.

If you want to be able to set a custom alphanumeric in the “From” as sender, please contact our sales team. Remember that there are country-specific restrictions when setting an alphanumeric senders, so it may not be allowed in specific countries.

Response

int - messageId

messageId is the unique id that was assigned to the SMS request. It can be used to later query the status of the SMS.

Example

{
    "messageId": 123
}

Check message status

[GET] /Sms/{messageId} - Checks the status of a SMS message.

Authorization

This is a protected resource and requires an application signed request or basic auth.

Request

Example

URL: [GET] https://messagingapi.sinch.com/v1/message/status/1234

Response

string - status

Example

{
    "status": "Successful"
}

status may have one of the following values:

  • Unknown - The provided message id is not known
  • Pending - The message is in the process of being delivered
  • Successful - The message has been delivered to the recipient
  • Faulted - The message has not been delivered. This status can be due to an invalid number for example.

Message size

Max number of characters per SMS depends on which alphabet is used. Default is the GCM 7-bit alphabet, but characters in languages such as Arabic, Chinese, Korean, Japanese, or Cyrillic alphabet languages (e.g., Ukrainian, Serbian, Bulgarian, etc) must be encoded using the 16-bit UCS-2 character encoding.

An SMS is 140 bytes. Depending on which alphabet is used, this leads to the maximum individual SMS sizes of 160 GCM 7-bit characters or 70 UCS-2 16-bit characters.

When sending concatenated SMS 6 bytes are allocated for segmentation and reassembly, which gives 153 characters per SMS instead of 160 for GCM 7-bit characters and 67 characters instead of 70 for UCS-2 16-bit characters.