websms| Messaging API Documentation (1.0.0)

Download OpenAPI specification:Download

Authentication

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

oauth2

Security Scheme Type OAuth2
clientCredentials OAuth Flow
Token URL: https://auth.websms.com/oauth/token
Scopes:
  • messaging:whatsapp -

    send whatsapp messages

  • messaging:rcs -

    send rcs messages

  • media:create -

    upload media files

  • media:read -

    download media files

Error Handling

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

Inbound Messages

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

Status Messages

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:

  • dispatched
  • delivered
  • read
  • failed

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

WhatsApp

Send text message

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.
Authorizations:
oauth2 (messaging:whatsapp)
Request Body schema: application/json
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

Responses

Request samples

Content type
application/json
{
  • "applicationId": "97ab27fa-30e2-43e3-92a3-160e80f4c0d5",
  • "recipient": "+436531234567",
  • "content": "Hello World",
  • "clientMessageId": "myclientid"
}

Response samples

Content type
application/json
{
  • "statusCode": 2000,
  • "statusMessage": "Request accepted",
  • "clientMessageId": null,
  • "transferId": "005d0666e100d97ccc31"
}

Send media message

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.
Authorizations:
oauth2 (messaging:whatsapp)
Request Body schema: application/json
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

Responses

Request samples

Content type
application/json
{
  • "applicationId": "97ab27fa-30e2-43e3-92a3-160e80f4c0d5",
  • "recipient": "+436531234567",
  • "mediaId": "5a8ffac5-2288-485d-b463-90c3cd9941ad",
  • "content": "Hello World",
  • "clientMessageId": "myclientid"
}

Response samples

Content type
application/json
{
  • "statusCode": 2000,
  • "statusMessage": "Request accepted",
  • "clientMessageId": null,
  • "transferId": "005d0666e100d97ccc31"
}

Send template message

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.
Authorizations:
oauth2 (messaging:whatsapp)
Request Body schema: application/json
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)

Responses

Request samples

Content type
application/json
{
  • "applicationId": "97ab27fa-30e2-43e3-92a3-160e80f4c0d5",
  • "recipient": "+436531234567",
  • "templateName": "order_confirmation",
  • "templateLocale": "en",
  • "clientMessageId": "myclientid",
  • "localizableParams": [
    ]
}

Response samples

Content type
application/json
{
  • "statusCode": 2000,
  • "statusMessage": "Request accepted",
  • "clientMessageId": null,
  • "transferId": "005d0666e100d97ccc31"
}

RCS

Send RCS message

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:

  • RCSMessage
  • messageContact

For concrete examples please check "Request samples". This section contains the following examples:

  • Text Message
  • Media Message
  • Standalone Card
  • Rich Card Carousel
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.
Authorizations:
oauth2 (messaging:rcs)
path Parameters
applicationId
required
string <uuid>
Example: 95ab0a2f-42f3-4da8-851b-7df772c94fca

UUID of the application

Request Body schema: application/json
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

Responses

Request samples

Content type
application/json
Example
{
  • "RCSMessage": {
    },
  • "messageContact": {
    }
}

Response samples

Content type
application/json
{
  • "RCSMessage": {
    }
}

Check for RCS capabilities

This method is used to check for the RCS capabilities for a specific msisdn.

Authorizations:
oauth2 (messaging:rcs)
path Parameters
applicationId
required
string <uuid>
Example: 95ab0a2f-42f3-4da8-851b-7df772c94fca

UUID of the application

query Parameters
userContact
required
string
Example: userContact=+43123456789

MSISDN to be queried

Responses

Response samples

Content type
application/json
{
  • "capabilities": [
    ]
}

Media

Upload a media to be used when sending media messages

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.
Authorizations:
oauth2 (media:create)
Request Body schema:
string <binary>

Responses

Response samples

Content type
application/json
{
  • "statusCode": 2000,
  • "statusMessage": "OK",
  • "mediaId": "5a8ffac5-2288-485d-b463-90c3cd9941ad"
}

Fetch media file (e.g. when received)

This method is used to read a multi media object

Authorizations:
oauth2 (media:read)
path Parameters
mediaId
required
string <uuid>

UUID of the media

Responses

Response samples

Content type
application/json
{
  • "statusCode": 4001,
  • "statusMessage": "Invalid applicationId"
}