--- title: "Custom SMS response" method: POST path: "/api/sms/custom-response" tags: ["SMS"] --- # Custom SMS response `POST /api/sms/custom-response` ## Request - Base URL: `https://go.urbanairship.com` - URL: `https://go.urbanairship.com/api/sms/custom-response` - Auth: HTTP bearer - TypeScript: (a function with typed inputs; its response is checked against the schema) Respond to a mobile-originated message based on a keyword consumed by your custom-response webhook, using a mobile-originated ID. See [SMS Keyword Webhooks](/developer/api-integrations/sms/inbound-message-handling/) for information about setting up a custom response webhook server. ## Headers - `X-UA-Appkey` string, required ## Request body - union - object - `mobile_originated_id` string, uuid, required: The identifier that you received through your SMS webhook corresponding to the mobile-originated message that you're issuing a custom response to. The `mobile_originated_id` is valid for 10 minutes from the `received_timestamp` in the payload sent to your webhook server's `/inbound-sms` endpoint. - `sms` object, required - `alert` string, required: Your custom SMS message. - `shorten_links` boolean: If true, Airship will shorten HTTP/HTTPS links (space delimited) in the message text fields, producing unique, 25 character URLs for each member of your audience. Airship produces `short_link_click` events in the Real-Time Data Stream for each link that a user engages with. When this setting is enabled, you can add or remove tags from users who click your links by adding query strings to your URLs. You can serialize tag operations with `&`: * `?ua-tag-add=tag_group:tag&another_group:tag2` — adds a tag in `tag_group` to the `channel_id`. * `?ua-tag-remove=tag_group:tag&another_group:tag2` — removes a tag in `tag group` from the `channel_id`. * `?ua-list-add=subscription_list_id` — adds the user's channel to the `subscription list`. * `?ua-list-remove=subscription_list_id` — removes the user's channel from the `subscription list`. - object - `mms` MmsOverrideObject, required: Provides the content for a push to MMS channels. If `sms` is in the `device_type` array, your request may include this object. It cannot be combined with an SMS Platform Override as a single push can only include either an SMS or MMS payload. - `fallback_text` string, required: If a member of your audience cannot receive MMS messages, they will receive your fallback text with a link to the original content. - `shorten_links` boolean: If true, Airship will shorten HTTP/HTTPS links (space delimited) in the message text fields, producing unique, 25 character URLs for each member of your audience. Airship produces `short_link_click` events in the Real-Time Data Stream for each link that a user engages with. When this setting is enabled, you can add or remove tags from users who click your links by adding query strings to your URLs. You can serialize tag operations with `&`: * `?ua-tag-add=tag_group:tag&another_group:tag2` — adds a tag in `tag_group` to the `channel_id`. * `?ua-tag-remove=tag_group:tag&another_group:tag2` — removes a tag in `tag group` from the `channel_id`. * `?ua-list-add=subscription_list_id` — adds the user's channel to the `subscription list`. * `?ua-list-remove=subscription_list_id` — removes the user's channel from the `subscription list`. - `slides` object[], required: An array containing a single slide object. A slide is a multimedia object. - `media` object, required: Contains information about the media you want to send. - `content_length` integer: The length of the attachment in bytes. Maximum size is 2 MB for `image/jpeg` and `image/png`, 1,024 KB for `image/gif` or `audio/.* MIME types`, and 2,048 KB for `text/vcard`. While this is optional, it is recommended since pushes will get dropped if the content size is incorrect. - `content_type` 'image/jpeg' | 'image/gif' | 'image/png' | 'text/vcard' | 'audio/wav' | 'audio/3gpp' | 'audio/3gpp2' | 'audio/mp4' | 'audio/mpeg', required: The MIME type of the image specified in the URL. The MIME type must match the extension in the `url`. - `url` string, required: The HTTP or HTTPS URL of the media attachment for the slide. The URL must end in one of `.gif`, `.jpeg`, `.jpg`, `.png`, `.mp1`, `.mp2`, `.mp3`, `.m1a`, `.m2a`, `.mpa`, `.wav`, `.3gp`, `.3g2`, `.m4a`, `.m4b`, `.m4r`, or `.vcf` (case-insensitive). While the `content_length` field is optional, your image must still be under 2 MB for JPEGs and PNGs, 1 MB for GIFs, or 2,048 KB for `text/vcard`. - `text` string: Text that you want to display along with the media attachment. The order of media and text in the message is not guaranteed. - `subject` string: The subject for the MMS message, normally displayed in bold. The subject might not appear for recipients if the Sender is a Toll-Free number. An empty string is valid. - `mobile_originated_id` string, uuid, required: The identifier that you received through your SMS webhook corresponding to the mobile-originated message that you're issuing a custom response to. The `mobile_originated_id` is valid for 10 minutes from the `received_timestamp` in the payload sent to your webhook server's `/inbound-sms` endpoint. ## Response `200` The operation was successful. - object - `ok` boolean: If `true`, your request was successful. - `operation_id` string, uuid: A unique identifier for an operation; you can use this identifier to find the operation for troubleshooting purposes. - `push_id` string, uuid: A unique identifier for a push operation. ## Other responses - `404`: The mobile_originated_id could not be found. ## Changes - **2026-06-24** `38241778b0c1`: 1 breaking - removed `subschema #1, subschema #2` from the request body `oneOf` list - …this revision’s changelog is incomplete - **2026-02-20** `e2bd980cb50b`: 1 breaking, 1 info - removed `subschema #1, subschema #2` from the request body `oneOf` list - added `subschema #1, subschema #2` to the request body `oneOf` list [Operation history](https://skmtc.dev/airship/apis/airship-api/changes/api/sms/custom-response/post.md) --- [API](https://skmtc.dev/airship/apis/airship-api.md) - [All operations](https://skmtc.dev/airship/apis/airship-api/llms.txt) - [OpenAPI document](https://skmtc.dev/airship/apis/airship-api/revisions/bd6ab947117a?raw)