Start enriching your app

Docs

SMS

Introduction

This document provides a detailed user guide and reference documentation on the Sinch SMS REST API. For general information on how to use the Sinch APIs including methods, types, errors and authorization, please check the Using REST page.

Overview

The SMS Messaging API allows you to send SMS messages to mobile phones and check their status using the Sinch platform. You can also rent SMS-enabled numbers from Sinch to receive inbound SMS messages from your users that are sent to the backend of your app. For more information see SMS-enabled numbers.

API Quick Reference

SMS Messaging API

URI: https://messagingapi.sinch.com/v1
URLHTTP VerbFunctionality
/Sms/{number}POSTSend SMS
/Sms/{messageId}GETGet status of SMS message


SMS Messaging Callback API

EventHTTP VerbFunctionality
incomingSmsPOSTIncoming SMS Event


Supported countries

You can use the Sinch platform to connect with the following countries:

Afghanistan Algeria Argentina Armenia Australia
Austria Azerbaijan Bahamas Bahrain Bangladesh
Belarus Belgium Bolivia Bosnia & Herzegovina Brasil
Bulgaria Cambodia Canada Central African Republic Chile
China Colombia Congo Congo D.R. Costa Rica
Croatia Cuba Cyprus Czech Republic Denmark
Ecuador Egypt Finland France Gabon
Gambia Georgia Germany Ghana Greece
Hong Kong Hungary India Indonesia Iran
Ireland Israel Italy Jamaica Japan
Kazakhstan Kenya Kuwait Kyrgyzstan Latvia
Lebanon Liberia Libya Lithuania Luxembourg
Macedonia Malaysia Mexico Moldova Monaco
Mongolia Morocco Netherlands New Zealand Nigeria
Norway Pakistan Panama Paraguay Peru
Philippines Poland Portugal Puerto Rico Qatar
Romania Russia Saudi Arabia Senegal Singapore
Slovakia Slovenia South Africa South Korea Spain
Sudan Sweden Switzerland Syria Taiwan
Thailand Tunisia Turkey Uganda United Kingdom
Ukraine United States Uruguay Venezuela Vietnam



Two-way SMS

The Sinch platform supports the provisioning of SMS-enabled numbers that can be used for two-way SMS. Through these numbers, you can send SMS messages to users and receive replies when a user replies to the particular SMS number. Messages that originate from a user’s mobile phone to the Sinch platform are called Mobile Originated (MO) SMS. To receive MO SMS messages, you need to rent a dedicated Long Number or Short Code which allows this type of messages. For more information see SMS-enabled numbers.

To receive an MO SMS message, you need to configure a callback URL and develop a backend application that can receive the SMS callback event. For more information, see SMS Messaging Callback API.

SMS to US numbers

To send SMS messages to US phone numbers in a production app, you need to rent an SMS-enabled number. SMS-enabled numbers can also be used to receive inbound SMS messages originating from mobile phones (MO). For more information see SMS-enabled numbers

SMS-enabled numbers

If the expected outbound SMS traffic is low, you can rent one or more Long Numbers. To rent a Long Number, log in to the Sinch portal with your Sinch account and go to the “Numbers” tab. After renting the needed numbers, you should go to your app SMS settings and assign the numbers to your app configuration.

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

For high-capacity SMS traffic or marketing campaigns, you will need to order a Short Code. To order and configure a Short Code for SMS in the Sinch platform, please contact our sales team.

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 platform.

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.


SMS Messaging Callback API

Overview

The Sinch platform supports notifying your backend application about incoming (MO) SMS through the messaging callback APIs.

To receive MO SMS messages you must have rented and configured an SMS-enabled number. To rent a Long Number, log in to the Sinch portal with your Sinch account and go to the “Numbers” tab. After renting the needed numbers, you should go to your app SMS settings and assign the numbers to your app configuration.

For more information see SMS-enabled numbers: Long Numbers and Short Codes

Incoming SMS Event Callback

When a MO SMS is received by the Sinch platform from a specific SMS-enabled number, the system sends a notification through a callback request to your backend application. The callback is a post request to a specified URL. URLs for callbacks need to be configured in the Sinch portal when creating or configuring an application.

The callback request is signed using the application key and secret. The application should be the one to which the SMS number is configured. You can find more information on callback request signing here.

Request

[RequestBody]
{
    string - event
    identity - to
    identity - from
    string - message
    time - timestamp
    int - version
}

event has the value “incomingSms”.

to shows the number where the SMS was sent to.

from shows the number that the SMS was sent from.

message the actual message content.

timestamp the timestamp when the SMS was received by the Sinch platform.

version is the SMS Callback API version

Example

{
    "event": "incomingSms",
    "to": {
        "type": "number",
        "endpoint": "+46700000000"
    },
    "from": {
        "type": "number",
        "endpoint": "+46700000001"
    },
    "message": "Hello world",
    "timestamp": "2014-12-01T12:00:00Z",
    "version": 1
}

Call Detail Records

CDRs can be downloaded from the Sinch portal. CDRs are in a semicolon-delimited file that contains the following fields

FieldTypeDescription
ApplicationKeystringApplication key
UserSpaceIdintInternal identifier
TimestamptimeTime when the SMS request was made
ResultstringResult may have one of the following values "Successful" | "Pending" | "Faulted" | "Unknown"
FromstringFrom number
TostringTo number
AmountdecimalCost of SMS message

The files are generated once daily and contain the previous days’ CDRs. A day spans from 00:00:00 UTC to 23:59:59 UTC. CDRs are written when the call is ended, though there are some edge cases where an app-app call CDR may be delayed in being written, for example, if there is a network failure before the call is ended.

CDR files can be downloaded from the developer portal. Upon request, the CDR files can also be uploaded to an Amazon S3 bucket that your company provides and to which Sinch has write access.

Glossary

TermExplanation
RTCReal Time Communication
SDKSoftware Development Kit
PSTNPublic Switched Telephone Network (plain old telephony)
RESTRepresentational State Transfer
APIApplication Programming Interface
ACEAnswered Call Event
ICEIncoming Call Event
DiCEDisconnected Call Event
CDRCall Detail Record
IMInstant Messages
User SpaceUniverse of unique user names
Data CallPhone call over the Internet, also known as "VoIP"
VoIPVoice over IP
CODECCoder/Decoder
HTTPHyper Text Transfer Protocol
RTPReal time Protocol
UDPUser Datagram Protocol
IVRInteractive Voice Response
CDRCall Detail Record
SMSShort Message Service
NATNetwork Address Translation
MXPMedia eXchange Protocol
SVAMLSinch Voice Application Markup Language