SMS Keyword 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 messagesA 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.

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

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.

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

You can test your inbound webhook and trigger keyword interactions on behalf of your audience, without receiving a mobile originated message, using the Airship API. See the Trigger Keyword Interaction endpoint for more information.

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_CHACHA20_POLY1305_SHA256
    • TLS_AES_256_GCM_SHA384
    • TLS_AES_128_GCM_SHA256

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.


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.

Registering your SMS Webhook

When you register a webhook in the Airship dashboard, Airship returns a Validation Code. You must set up your webhook to respond to GET requests to a /validate endpoint with a confirmation_code key containing this value before you enable the webhook in Airship.

  1. Go to Settings » Channels » SMS and click Manage for 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, and the page will update with a validation code.
  7. Configure your webhook to respond to GET requests to a /validate endpoint with a confirmation_code key containing the validation code value in a 200 response.
    GET <yourWebhookServer>/validate HTTP/1.1
    Example response
    HTTP/1.1 200 OK
    Content-Type: application/json
  8. Select Enabled, 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.


Before you disable a webhook, check with your Airship account manager to make sure that you aren’t sending any keywords to the webhook.

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",
   "operator_timestamp": "2019-04-29T11:58:13.100"

  • msisdn (string) – The MSISDNThe 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 IDAn originating phone number or string identifier used to indicate who an SMS message comes from. Members of your audience subscribe (opt in) to each 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.


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 to Mobile-Originated Messages

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 Token authorization. You must create a token with the All Access role to send custom responses. See Creating bearer tokens in Airship API Security.

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"