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 inbound messages 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 A message sent from a member of your audience (originating from the mobile handset of a user) to you. .

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 Airship. For example, if users want to 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.

The payload Airship sends to your webhook's /inbound-sms endpoint includes a mobile_originated_id that represents an individual mobile-originated 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.

Your webhook must support two endpoints:

  • /inbound-sms (POST) - An endpoint to receive SMS inbound message payloads from Airship.
  • /validate (GET) - An endpoint to receive a validation object from Airship. You must respond to the validation with the Validation Code issued when you set up your webhook in Airship.

After you set up your webhook in the dashboard, you must contact your Airship account manager to determine the static or variable keywords that you want to route to your webhook.

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

Example Response

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


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
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"

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 for when Airship received the mobile-originated message. The timestamp represents the beginning of a 10-minute window to send a response to the mobile_originated_id. Airship returns a 400 if you attempt to respond more than 10 minutes after the received_timestamp.

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 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; after 10 minutes, the mobile_originated_id expires.

The sms/custom-response API requires a specialized bearer token for authorization. Talk to your Airship account manager to get or expire bearer tokens for the Custom Response API.

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"