Download OpenAPI specification:Download
The websms| Messaging API supports the oauth2.0 client credentials flow (RFC 6749), please see section Security for further information.
The CLIENT_ID and CLIENT_SECRET used to obtain the access token will be provided upon request by your key account.
Additional the oauth2.0 framework uses scopes to provide a certain rights management for specific endpoints. The api client needs to request the scopes messaging:whatsapp, messaging:rcs, media:create and media:read in order to fully operate on the messaging API.
POST /oauth/token HTTP/1.1
Host: auth.websms.com
Content-Type: application/x-www-form-urlencoded
Authorization: Basic client_id:client_secret (client_id:client_secret must be base64 encoded)
grant_type=client_credentials&
scope=messaging:whatsapp%20messaging:rcs%20media:create%20media:read
A successful response will contain the access token in the following format. Access tokens expire after some time as a security measure. A oauth2.0 compatible client application has to renew the access token using this same token request after expiry.
HTTP/1.1 200 OK
Content-Type: application/json
{
"access_token": "eyJhbGciO.....Qssw5c",
"token_type": "bearer",
"expires_in": 300
}
Once the access token is obtained, it has to be provided as a bearer token within the Authorization http header (Bearer Token Usage RFC 6750).
POST /messaging/whatsapp/send_text HTTP/1.1
Host: api.websms.com
Authorization: Bearer <ACCESS_TOKEN>
Example using the access token as bearer authorization
Basically, the websms| REST API uses HTTP status codes to indicate errors.
For example a HTTP status code 400 (Bad request) means that the request made to the api could not be accepted while a HTTP status code 404 (Not found) means that either a non existent endpoint has been called or a needed entity to fulfill the request is not available (e.g. a referenced attachment doesn't exists when sending a message).
To provide further information an ErrorResponse document is returned describing the parameter and the reason (status_code, status_message) for the error.
HTTP/1.1 400 Bad Request
Content-Type: application/json;charset=UTF-8
{
"statusCode": 4009,
"statusMessage": "No message content provided"
}
Example ErrorResponse for a required parameter "content" was not set
To receive messages, sent from devices to a messenger application, a webhook URL has to be provided.
The websms| backend will send JSON documents as HTTP POST requests to the given URL in the following format. This format is basically the same as used for text messages, extended by the type of messenger (e.g. whatsapp) and an optional mediaId to indicate that a media file is attached.
Depending on the type of messenger used, the sender may be a user id instead of a phone number and the recipient can be optional. WhatsApp uses phone numbers.
To download the attached media the /messaging/media/{mediaId} endpoint has to be used.
POST /your/webhook/url HTTP/1.1
Host: your.domain.name
Content-Type: application/json;charset=UTF-8
{
"type": "whatsapp",
"applicationId": "E425269F-7815-45AC-B79A-F0DD402ECD17",
"sender": "+436761234567",
"user": {
"displayName": "The user"
},
"recipient": "+436761234567",
"content": "Hello World!",
"mediaId": "0F6368DC-6D35-430A-B739-1245ED1457A5"
}
Example inbound message request to your webhook
To confirm the receipt of an inbound message, your webhook has to respond with the following JSON document. Otherwise the websms| backend will continue to retry delivery unless the proper response is received.
HTTP/1.1 200 OK
Content-Type: application/json;charset=UTF-8
{
"statusCode": 2000,
"statusMessage": "Request processed"
}
Example inbound message response by your webhook to indicate positive processing
Receiving status messages for outgoing messages follows the same principle as receiving inbound messages. To receive status messages a separate webhook URL has to be provided.
The following message status updates are supported:
The websms| backend will send JSON documents as HTTP POST requests to the given URL in the following format.
POST /your/webhook/url HTTP/1.1
Host: your.domain.name
Content-Type: application/json;charset=UTF-8
{
"applicationId": "E425269F-7815-45AC-B79A-F0DD402ECD17"
"sender": "+436991234567"
"transferId": "005f21626a001102e7f2"
"messageStatus": "delivered"
"deliveredOn": "2020-07-29T13:50:06.000+02:00"
"clientMessageId": "myMessageId"
}
Example status message request to your webhook
To confirm the receipt of a status message, your webhook has to respond with the following JSON document. Otherwise the websms| backend will continue to retry delivery unless the proper response is received.
HTTP/1.1 200 OK
Content-Type: application/json;charset=UTF-8
{
"statusCode": 2000,
"statusMessage": "Request processed"
}
Example status message response by your webhook to indicate positive processing
This method is used to send a WhatsApp text message to a recipient.
statusCode | status | statusMessage |
---|---|---|
2000 | OK | Request accepted. |
4001 | INVALID_APPLICATION | The sending application is invalid. |
4002 | INVALID_RECIPIENT | One or more recipients are not in the correct format or are containing invalid msisdns. |
4008 | INVALID_MESSAGE_ID | Invalid clientMessageId. |
4013 | MSG_LIMIT_EXCEEDED | The accounts maximum message limit is reached |
4014 | UNAUTHORIZED_IP | Sender IP address is not authorized. |
4023 | THROTTLING_SPAMMING_IP | Request limit exceeded for this IP address. |
4028 | INVALID_CONTENT | Message text (content) is invalid. |
4029 | RECIPIENTS_NOT_ALLOWED | The provided recipients are not allowed (e.g. non whitelisted country prefix) |
4031 | RECIPIENTS_BLACKLISTED | All recipients are blacklisted. |
4400 | SESSION_EXPIRED | Customer care session window expired. |
5000 | INTERNAL_ERROR | Internal Error. |
5003 | SERVICE_UNAVAILABLE | Service Unavailable. |
messaging:whatsapp
) applicationId required | string <uuid> the uuid of the sending application |
recipient required | string recipient as E164 formatted MSISDN |
content required | string [ 1 .. 4096 ] characters UTF8 encoded message content |
clientMessageId | string client defined messageId |
{- "applicationId": "97ab27fa-30e2-43e3-92a3-160e80f4c0d5",
- "recipient": "+436531234567",
- "content": "Hello World",
- "clientMessageId": "myclientid"
}
{- "statusCode": 2000,
- "statusMessage": "Request accepted",
- "clientMessageId": null,
- "transferId": "005d0666e100d97ccc31"
}
This method is used to send a WhatsApp multi media message to a recipient.
statusCode | status | statusMessage |
---|---|---|
2000 | OK | Request accepted. |
4001 | INVALID_APPLICATION | The sending application is invalid. |
4002 | INVALID_RECIPIENT | One or more recipients are not in the correct format or are containing invalid msisdns. |
4008 | INVALID_MESSAGE_ID | Invalid clientMessageId. |
4013 | MSG_LIMIT_EXCEEDED | The accounts maximum message limit is reached |
4014 | UNAUTHORIZED_IP | Sender IP address is not authorized. |
4023 | THROTTLING_SPAMMING_IP | Request limit exceeded for this IP address. |
4028 | INVALID_CONTENT | Media description (content) is invalid. |
4029 | RECIPIENTS_NOT_ALLOWED | The provided recipients are not allowed (e.g. non whitelisted country prefix) |
4031 | RECIPIENTS_BLACKLISTED | All recipients are blacklisted. |
4034 | INVALID_MEDIA | Invalid media or mediaId |
5000 | INTERNAL_ERROR | Internal Error. |
5003 | SERVICE_UNAVAILABLE | Service Unavailable. |
messaging:whatsapp
) applicationId required | string <uuid> the uuid of the sending application |
recipient required | string recipient as E164 formatted MSISDN |
mediaId required | string <uuid> the uuid of the media item |
content | string <= 4096 characters UTF8 encoded message content |
clientMessageId | string client defined messageId |
{- "applicationId": "97ab27fa-30e2-43e3-92a3-160e80f4c0d5",
- "recipient": "+436531234567",
- "mediaId": "5a8ffac5-2288-485d-b463-90c3cd9941ad",
- "content": "Hello World",
- "clientMessageId": "myclientid"
}
{- "statusCode": 2000,
- "statusMessage": "Request accepted",
- "clientMessageId": null,
- "transferId": "005d0666e100d97ccc31"
}
This method is used to send a WhatsApp template message to a recipient.
Placeholders have to be submitted using the localizableParams property. Each map entry may contain exactly one key-value pair. The personalized content must not exceed a maximum length of 4096. Placeholder values must not contain newlines and must not exceed a maximum length of 1024. Currently "default" is the only supported localizable parameter type.
{
"applicationId": "95ab0a2f-42f3-4da8-851b-7df772c94fca",
"clientMessageId": "myid",
"localizableParams": [
{
"default": "first placeholder"
},
{
"default": "second placeholder"
},
{
"default": "third placeholder"
}
],
"recipient": "+436761234567",
"templateLocale": "en",
"templateName": "ticket_reactivation"
}
Example TemplateMessageSendRequest for a sending a template containing placeholders
statusCode | status | statusMessage |
---|---|---|
2000 | OK | Request accepted. |
4001 | INVALID_APPLICATION | The sending application is invalid. |
4002 | INVALID_RECIPIENT | One or more recipients are not in the correct format or are containing invalid msisdns. |
4008 | INVALID_MESSAGE_ID | Invalid clientMessageId. |
4013 | MSG_LIMIT_EXCEEDED | The accounts maximum message limit is reached |
4014 | UNAUTHORIZED_IP | Sender IP address is not authorized. |
4023 | THROTTLING_SPAMMING_IP | Request limit exceeded for this IP address. |
4028 | INVALID_CONTENT | Message Content (template name or locale) is invalid. |
4029 | RECIPIENTS_NOT_ALLOWED | The provided recipients are not allowed (e.g. non whitelisted country prefix) |
4031 | RECIPIENTS_BLACKLISTED | All recipients are blacklisted. |
4401 | INVALID_LOCALIZABLE_PARAMS | Invalid localizable params. The personalized content must not exceed a maximum length of 4096. Placeholder values must not contain newlines and must not exceed a maximum length of 1024. Currently "default" is the only supported localizable parameter type. |
5000 | INTERNAL_ERROR | Internal Error. |
5003 | SERVICE_UNAVAILABLE | Service Unavailable. |
messaging:whatsapp
) applicationId required | string <uuid> the uuid of the sending application |
recipient required | string recipient as E164 formatted MSISDN |
templateName required | string UTF8 encoded template identifier |
templateLocale required | string UTF8 encoded template locale |
clientMessageId | string client defined messageId |
Array of objects the localizable params (placeholder) |
{- "applicationId": "97ab27fa-30e2-43e3-92a3-160e80f4c0d5",
- "recipient": "+436531234567",
- "templateName": "order_confirmation",
- "templateLocale": "en",
- "clientMessageId": "myclientid",
- "localizableParams": [
- {
- "default": "first placeholder"
}, - {
- "default": "second placeholder"
}, - {
- "default": "third placeholder"
}
]
}
{- "statusCode": 2000,
- "statusMessage": "Request accepted",
- "clientMessageId": null,
- "transferId": "005d0666e100d97ccc31"
}
This method is used to send a RCS message to a recipient.
The body consists of two mandatory objects as specified in the RCS MaaP Chatbot API Specifications - 3.1.2.1:
For concrete examples please check "Request samples". This section contains the following examples:
Standalone Card | Rich Card Carousel |
statusCode | status | statusMessage |
---|---|---|
2000 | OK | Request accepted. |
4001 | INVALID_APPLICATION | The sending application is invalid. |
4008 | INVALID_MESSAGE_ID | Invalid clientMessageId. |
4013 | MSG_LIMIT_EXCEEDED | The accounts maximum message limit is reached |
4014 | UNAUTHORIZED_IP | Sender IP address is not authorized. |
4023 | THROTTLING_SPAMMING_IP | Request limit exceeded for this IP address. |
4120 | ENTITY_NOT_FOUND | Entity not found. |
5000 | INTERNAL_ERROR | Internal Error. |
5003 | SERVICE_UNAVAILABLE | Service Unavailable. |
messaging:rcs
) applicationId required | string <uuid> Example: 95ab0a2f-42f3-4da8-851b-7df772c94fca UUID of the application |
RCSMessage required | object the RCSMessage as specified in RCS MaaP Chatbot API Specifications - 3.1.2.1 |
messageContact required | object the messageContact as specified in RCS MaaP Chatbot API Specifications - 3.1.2.1 |
{- "RCSMessage": {
- "textMessage": "hello world"
}, - "messageContact": {
- "userContact": "+436531234567"
}
}
{- "RCSMessage": {
- "msgId": "abc123",
- "status": "pending"
}
}
This method is used to check for the RCS capabilities for a specific msisdn.
messaging:rcs
) applicationId required | string <uuid> Example: 95ab0a2f-42f3-4da8-851b-7df772c94fca UUID of the application |
userContact required | string Example: userContact=+43123456789 MSISDN to be queried |
{- "capabilities": [
- "chat",
- "chatBotCommunication",
- "fileTransfer",
- "geolocationPush"
]
}
This method is used to create a multi media object
statusCode | status | statusMessage |
---|---|---|
2000 | OK | Request accepted. |
4034 | INVALID_MEDIA | Invalid media. |
5000 | INTERNAL_ERROR | Internal Error. |
5003 | SERVICE_UNAVAILABLE | Service Unavailable. |
media:create
) {- "statusCode": 2000,
- "statusMessage": "OK",
- "mediaId": "5a8ffac5-2288-485d-b463-90c3cd9941ad"
}
This method is used to read a multi media object
media:read
) mediaId required | string <uuid> UUID of the media |
{- "statusCode": 4001,
- "statusMessage": "Invalid applicationId"
}