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.
Talk to 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.
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 OKand 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-responseendpoint) within 10 minutes of the
Accept HTTPS connections.Airship uses TLSv1.2 with the following accepted cipher suites:
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.
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.
- Go to Settings » Channels » SMS Webhooks.
- Click Configure New SMS Webhook.
- Enter a name for the webhook. This is just a friendly name to help you recognize your webhooks in Airship.
- Enter the Webhook URL. This is the base URL of your webhook server. Your webhook server is expected to support
- 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-SIGNATUREheader to authenticate with your webhook server.
- Click Save. Airship issues a Validation Code. Before you enable the webhook, you must configure your webhook provide a
confirmation_codecontaining this value in a
200response to a
GETrequest to your webhook server's
- 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
application/json, and the
confirmation_code when requested.
GET <yourWebhookServer>/validate HTTP/1.1 Host: example.com
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 Host: example.com Authorization: Basic <configured user:pass> Content-type: application/json
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 IDThe 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
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
X-UA-TIMESTAMPheader — the unix timestamp when the request was sent.
- 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.
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.
/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