Definitions, Formats & Errors
Definitions
Sender Identity
The Application-to-Person (A2P) agent that sends messages to the end user, sometimes referred to as a chat bot, bot or agent.
Sender ID
The unique identifier for the Sender Identity registered on the Sinch platform.
Example: AbCDEfghIJKlMNop
NOTE:
Please contact your Sinch account manager to get your Sender ID.
User Agent
The end users messaging application on device that receives messages from the Agent and sends messages, events and status back to the RCS API.
Data formats
JSON
JSON (application/json) is the content type of both requests and responses if not otherwise specified. Requests with invalid JSON will be rejected.
Null values can be omitted in requests and will be omitted in responses. In some cases explicitly setting null will overwrite a previously set value with null.
MSISDN
An MSISDN is the phone number associated with a single SIM card. Only MSISDNs in international E.164 format are accepted by the API.
MSISDNs can be sent in with or without a leading + or 00 (+123456789, 00123456789 and 123456789 are equivalent). Any spaces, dashes or brackets, will be ignored by the API.
All MSISDNs returned by the REST API will be without a + or 00 prefix, even if they were originally sent in with one.
Timestamps
Timestamps are represented using the ISO-8601 standard.
All timestamps returned will be in UTC with millisecond precision.
The time zone can be specified in accordance with ISO-8601. If no time zone offset is specified (local time in ISO-8601) then UTC will be used.
Errors
The REST API returns the appropriate HTTP status codes for the request made. Such as 200 OK
, 401 Unauthorized
or a 400 Bad Request
.
When an 4XX HTTP error is returned the response body also contains an Error object with more information.
For example, a 400 Bad Request
could be due to Missing Required Property
or Invalid Property
.
Error Codes
To distinguish these errors, the response body has an API error_code
property.
HTTP STATUS | API Error Code | Description |
---|---|---|
500 | 1 | Unknown server error |
1000 | Invalid JSON | |
1001 | Invalid API message | |
400 | 1002 | Invalid property value |
1003 | Mismatched input | |
400 | 1004 | Missing required property |
400 | 1005 | Invalid property value |
400 | 1006 | Invalid property value |
1007 | Missing property | |
1010 | Couldn't handle the input | |
401 | 1011 | Unauthorized |
404 | 1014 | Subscriber not found (MISDIN not valid or not registered to with an RCS provider) |
404 | N/A | Some 404 errors have no body |
405 | N/A | Method not allowed (has body but no error_code field) |
409 | N/A | Conflict (Empty body - delete a message that has been deleted) |