Inbound Message Handling

Set up a webhook to receive and respond to messages from your audience that contain keywords.

Inbound message handling uses an SMS keyword webhook. Airship forwards mobile originated messages A message sent from a member of your audience (originating from the mobile handset of a user) to you. from your audience to your webhook so you can process requests from your audience and send custom, targeted responses to individual members of your audience based on the keywords they use in mobile originated messages.

You can use a webhook to respond to mobile-originated messages when either the keyword or the information you want to respond with are variable and defined outside of Airship. For example, if users text the defined keyword balance to your sender ID, you can use a webhook to process incoming messages and respond with each individual user's balance. If a user texts a variable keyword, like order <#orderNumber>, you can use a webhook to respond with the status of the specified order number.

Talk to your Airship account manager to determine the static or variable keywords that you want to route to your webhook.

sequenceDiagram Audience->>Airship: Sends MO with Keyword rect rgba(0, 179, 6, .2) Airship->>Webhook: Forwards MO to Webhook Webhook-->>Airship: Respond HTTP 200, process asynchronously note over Airship, Webhook: Airship retries on 429/503 up to 4x end Webhook->>Airship: Issue custom response < 10 min Airship->>Audience: Sends custom response

Airship sends a payload to your webhook server at an /inbound-sms endpoint containing a mobile_originated_id that represents an individual MO message. You will use this ID and send a response using the /sms/custom-response API. Because you are responding to a message sent to you by a member of your audience, custom responses do not require users to opt in. However, the mobile_originated_id has a 10-minute lifespan; you have 10 minutes from the time a mobile-originated message is received to issue a response, after which the mobile_originated_id expires and you will be unable to respond to the inbound message.

SMS Webhook Requirements

Your webhook server must:

  • Have a public URL. Airship server IPs regularly change and must be able to reach your webhook.
  • Support an /inbound-sms (POST) endpoint to receive SMS inbound message payloads from Airship. Your webhook should immediately respond with HTTP 200 OK and process responses asynchronously. Long-lived connections can cause performance problems on both systems.
  • Support a /validate (GET) endpoint. You must respond to a validation request with the Validation Code issued when you set up your webhook in Airship.
  • Issue responses (to Airship's /sms/custom-response endpoint) within 10 minutes of the received_timestamp in the /inbound-sms payload.
  • Accept HTTPS connections.Airship uses TLSv1.2 with the following accepted cipher suites:

    • TLS_ECDHE_RSA_WITH_AES_256_CBC_SHA
    • TLS_ECDHE_RSA_WITH_AES_256_GCM_SHA384
    • TLS_ECDHE_RSA_WITH_AES_256_CBC_SHA384
    • TLS_ECDHE_ECDSA_WITH_AES_256_CBC_SHA
    • TLS_ECDHE_ECDSA_WITH_AES_256_GCM_SHA384
    • TLS_ECDHE_ECDSA_WITH_AES_256_CBC_SHA384

Additional Recommendations

Your webhook server should accept up to 100 concurrent connections. Airship will establish concurrent connections with your webhook when concurrent incoming messages require processing.

Retries

Airship will retry connections to your webhook when your webhook responds with 429 (Too Many Requests) or 503 (Service Unavailable) HTTP codes.

When Airship receives a retryable error, Airship will retry up to 4 times (5 total attempts) over 30 seconds. After the fourth retry (the fifth request), Airship will drop the request.

Airship does not retry on other 4xx or 5xx HTTP codes or HTTP timeouts; Airship's timeout duration is 10 seconds. Our approach to retries is designed to prevent your users from receiving duplicate messages.

Register your SMS Webhook

As a part of this process, Airship issues a Validation Code. You will not be able to enable your webhook until you configure it to respond to GET requests to a /validate endpoint with a validation_code key containing this value.

  1. Open your messaging project and go to Settings » Channels » SMS Webhooks.
  2. Click Configure New SMS Webhook.
  3. Enter a name for the webhook. This is just a friendly name to help you recognize your webhooks in Airship.
  4. Enter the Webhook URL. This is the base URL of your webhook server. Your webhook server is expected to support <base Url>/validate and <base URL>/inbound-sms endpoints.
  5. Select the Authentication mechanism for your webhook.
    • Basic: Enter the Username and Password that Airship will use to authenticate with your webhook server.
    • Signature: Enter the Secret Key that Airship will use as a part of an X-UA-SIGNATURE header to authenticate with your webhook server.
  6. Click Save. Airship issues a Validation Code. Before you enable the webhook, you must configure your webhook provide a confirmation_code containing this value in a 200 response to a GET request to your webhook server's /validate endpoint.
  7. After you have set up your webhook to respond with the validation code, select Enabled to enable the webhook, then click Update.

When you enable the webhook, Airship issues a request to your webhook's /validate endpoint. If successful, your webhook will begin receiving requests at the /inbound-sms endpoint. Contact your Airship account manager to determine the keywords you want to route to your webhook server.

Validating your Webhook

When you register your webhook server with Airship, Airship responds with a Validation Code. Your webhook server must support a /validate endpoint that responds with a 200 OK, a content-type of application/json, and the confirmation_code when requested.

GET <yourWebhookServer>/validate HTTP/1.1
Host: example.com

Example Response

HTTP/1.1 200 OK
Content-Type: application/json

{
   "confirmation_code":"559384cd-6284-4e3e-9e4e-7c260019a251"
}

confirmation_code (string) — The confirmation code given to you by Airship.

Accepting Inbound SMS Messages

Your webhook server must accept POST requests to an <yourWebhookServer>/inbound-sms endpoint. Each request contains a payload representing a mobile-originated message containing specific keyword or an unrecognized keyword (as set up through your Airship account manager).

POST <yourWebhookServer>/inbound-sms HTTP/1.1
Host: example.com
Authorization: Basic <configured user:pass>
Content-type: application/json

{
   "msisdn": "15035551234",
   "sender": "28444",
   "app_key": "1Drc_YYKTistxd0-p_Hljh",
   "channel_id": "a828de17-b315-4e80-9d2d-35a906afeacf",
   "mobile_originated_message": "balance",
   "mobile_originated_id": "28883743-4868-4083-ab5d-77ac4542531a",
   "received_timestamp": "2019-04-29T12:00:01.492",
   "operator_timestamp": "2019-04-29T11:58:13.100"
}

msisdn (string) – The MSISDN The mobile phone number of an individual in your Airship audience. Each MSISDN represents an individual mobile device. of the audience member (mobile device) who sent the mobile-originated message.

sender (string) – The Sender ID The alphanumeric code that your SMS messages come from — like a phone number or name. Your audience subscribes to each individual sender ID they want to receive messages from. that received the mobile-originated message. This is important if you have more than one sender.

app_key (string) – The app key that the sender is configured for.

channel_id (string) – (Optional) The channel ID associated with the MSISDN/sender. You can use this value to make opt-in, opt-out, or tag changes. If a channel does not exist for the MSISDN/sender and the keyword is not configured to create a channel if none exists, this field is absent.

mobile_originated_message (string) – The contents of the mobile-originated message; this message consists of, or contains, a keyword.

mobile_originated_id (string) – A unique ID for the message. Use this ID to respond to the mobile-originated message.

received_timestamp (string) — An ISO-8601 UTC timestamp of the current time (the time of the webhook request). This represents the beginning of a 10-minute window to send a response to the mobile_originated_id.

operator_timestamp (string) — An ISO-8601 UTC timestamp of when the mobile-originated message was originally sent, according to the carrier or aggregator.

 Note

Due to carrier maintenance and delays outside of Airship's control, mobile-originated messages can arrive at the webhook significantly after they are sent from the device (represented by the operator_timestamp). You may want to alter your messaging if a mobile-originated message is not received in a timely manner.

Webhook Signature Hash Security

Rather than basic authentication, you can configure a signature that your webhook server can use to verify that requests come from Airship. To enable this signature, select Signature Hash authorization and set a secret_key when configuring your webhook or open channel.

When you enable and set a secret_key, outgoing requests include a hash-based authentication code computed using the sha256 hash function in an X-UA-SIGNATURE header. You can use this same algorithm to verify the signature on the receiving server.

X-UA-SIGNATURE is composed of the secret_key and a message, both of which must be UTF-8 encoded. The message is a concatenation of the following string values:

  • The X-UA-TIMESTAMP header — the unix timestamp when the request was sent.
  • The : character.
  • The JSON request body.

To prevent replay attacks, you should validate the X-UA-TIMESTAMP within a threshold of the current time. We recommend that you use a 5-minute threshold to account for time drift, though Airship uses NTP and we recommend that your webhook server does the same. To prevent timing attacks, you should employ a constant time-compare function when checking signatures.

Request headers with secret key
POST /yourWebhookServer/push HTTP/1.1
Content-Type: application/vnd.urbanairship+json; version=3;
Content-encoding: gzip
X-UA-TIMESTAMP: 1536947409
X-UA-SIGNATURE: 68688b9dbd5c381851d3cd51dba3093c6633ceef58e6fee6ad4757f857f59aea
Data-Attribute: values

Sending Custom Responses

You can issue custom SMS or MMS responses to mobile-originated messages using the mobile_originated_id. You have 10 minutes from the received_timestamp to respond to a mobile-originated message; the mobile_originated_id expires after 10 minutes.

The /sms/custom-response API uses bearer authorization. You must create a token with the All Access role to send custom responses.

POST /api/sms/custom-response HTTP/1.1
Authorization: Bearer <bearer token>
X-UA-Appkey: <app key>
Accept: application/vnd.urbanairship+json; version=3;
Content-type: application/json

{
   "sms" : {
      "alert": "Your balance is $12.34"
   },
   "mobile_originated_id" : "28883743-4868-4083-ab5d-77ac4542531a"
}