openapi: 3.2.0 info: title: Transmit Message Webhook API description: Transmit APIs version: '20250101' x-go-package: github.com/oapi-codegen/runtime servers: - url: https://api.transmitmessage.com security: - ApiKeyAuth: [] tags: - name: Webhook description: "Our webhooks API allows you to subscribe to events for SMS, MMS, and RCS messages. Using them requires you to have URLs (https) configured on your account that can receive POST requests over the internet.\n\nThe `event_type` field is an enum that specifies which event to subscribe to:\n\n- LINK_HIT\n- OPT_OUT\n- MMS_STATUS\n- MMS_INBOUND\n- SMS_INBOUND\n- SMS_STATUS\n- RCS_STATUS\n \n\nFor status events, the nested `status` field is an enum with these values:\n\n- FAILED: Failed because of an error from the carrier or handset.\n \n- SENT: Submitted to the carrier.\n- ACCEPTED: Accepted by the carrier and delivery may have been attempted (but is not confirmed).\n- DELIVERED: Delivered to handset.\n- SOFT_BOUNCE: Undeliverable due to handset being switched off, out of range or other temporary deliverability issue.\n- HARD_BOUNCE: Handset was disconnected.\n- OTHER: Any other status from the carrier.\n \n\n## Link Hit\n\nThe `LINK_HIT` event is triggered any time a recipient visits a link that is tracked. Track Links is an optional flag on the send message API calls. Along with the URL that was being tracked is a hits field indicating how many visits this tracked link has in total and a source_message which contains the track link sent to the recipient.\n\n###### Example Payloads\n\n```json Hit link in MMS {\n \"event_type\": \"LINK_HIT\",\n \"timestamp\": \"2021-05-06T05:19:42Z\",\n \"link_hit\": {\n \"hits\": 1,\n \"url\": \"https://www.example.com/abc\",\n \"source_message\": {\n \"type\": \"MMS\",\n \"id\": \"b50e4dc1-e57f-459c-a15c-526bee00a4c4\",\n \"message\": \"Hey, Check this out! http://clckme.info/KYhSsuIH Opt-out reply STOP\",\n \"message_ref\": \"D701\",\n \"recipient\": \"61435790000\",\n \"sender\": \"61481074191\",\n \"subject\": \"Hello\",\n \"content_urls\": [\n \"https://res.cloudinary.com/burstsms/image/upload/v1618798563/284KB_qgqtbe.jpg\"\n ]\n }\n }\n} ``` ```json Hit link in SMS {\n \"event_type\": \"LINK_HIT\",\n \"timestamp\": \"2021-07-20T23:14:04Z\",\n \"link_hit\": {\n \"hits\": 1,\n \"url\": \"https://www.example.com/abc\",\n \"source_message\": {\n \"type\": \"SMS\",\n \"id\": \"faf68308-16cd-4cf9-aef7-47342bd405be\",\n \"message\": \"Hey, Check this out! http://clckme.info/KYhSsuIH for Opt-out reply STOP or hit opt out link - http://nsub.me/vqHTcCsh \",\n \"message_ref\": \"D301\",\n \"recipient\": \"61435795809\",\n \"sender\": \"61481074185\"\n }\n }\n} ```\n## Opt Out\n\nThe `OPT_OUT` event is triggered when a recipient has visited an opt-out link in a message they have received or by sending a message with the text \"STOP\".\n\nUsing parameter \\[opt-out-link\\] in message body, inserts the opt-out link.\n\nThe source field will be set according to the method a recipient has used to opt-out and contain a value of either link or SMS.\n \n\n###### Example Payloads\n\n```json Opt out via link {\n \"event_type\": \"OPT_OUT\",\n \"timestamp\": \"2021-05-06T05:16:20Z\",\n \"opt_out\": {\n \"source\": \"LINK_HIT\",\n \"source_message\": {\n \"type\": \"SMS\",\n \"id\": \"a51ebe4e-a412-440e-a8d9-464e68a521cc\",\n \"message\": \"Hey, Check this out! http://clckme.info/KYhSsuIH for Opt-out reply STOP or hit opt out link - http://nsub.me/vqHTcCsh\",\n \"message_ref\": \"ncc5009d\",\n \"recipient\": \"61435790000\",\n \"sender\": \"61481074190\" \n }\n }\n} ``` ```json Opt out via message {\n \"event_type\": \"OPT_OUT\",\n \"timestamp\": \"2021-05-06T05:16:20Z\",\n \"opt_out\": {\n \"source\": \"SMS_INBOUND\",\n \"source_message\": {\n \"type\": \"SMS\",\n \"id\": \"a51ebe4e-a412-440e-a8d9-464e68a521cc\",\n \"message\": \"Hey, Check this out! http://clckme.info/KYhSsuIH for Opt-out reply STOP or hit opt out link - http://nsub.me/vqHTcCsh\",\n \"message_ref\": \"ncc5009d\",\n \"recipient\": \"61435790000\",\n \"sender\": \"61481074190\"\n }\n }\n} ```\n## MMS Status\n\nThe `MMS_STATUS` event data is posted to you for changes to an MMS message status. These are currently only comprised of internal statuses (SENT, FAILED).\n\n###### Example Payload\n\n```json {\n \"event_type\": \"MMS_STATUS\",\n \"timestamp\": \"2021-05-06T05:19:33Z\",\n \"status\": {\n \"type\": \"MMS\",\n \"id\": \"b50e4dc1-e57f-459c-a15c-526bee00a4c4\",\n \"message_ref\": \"D7001\",\n \"recipient\": \"61435790000\",\n \"sender\": \"61481074191\",\n \"status\": \"SENT\"\n }\n} ```\n## SMS Inbound\n\nThe `SMS_INBOUND` event is posted to you on receipt of an SMS sent from a recipient to one of the senders listed on your account. For convenience we will try and find a message that you have sent to this recipient from that sender and supply it as the `last_message` field. This is useful for determining if an inbound message is potentially a reply. The `routed_via` field will display when a shared local number has been used to deliver your message.\n\n###### Example Payload\n\n```json {\n \"event_type\": \"SMS_INBOUND\",\n \"timestamp\": \"2021-05-06T05:16:33Z\",\n \"mo\": {\n \"type\":\"SMS\",\n \"id\": \"alss-2way-605b31c7-d2c49104\",\n \"message\": \"Stop\",\n \"recipient\": \"61481074190\",\n \"routed_via\": \"447507333300\",\n \"sender\": \"447507222200\",\n \"last_message\": {\n \"type\":\"SMS\",\n \"id\": \"a51ebe4e-a412-440e-a8d9-464e68a521cc\", \n \"message\": \"Hey, check this out!\",\n \"message_ref\": \"ncc5009d\",\n \"recipient\": \"447507222200\",\n \"routed_via\": \"447507333300\",\n \"sender\": \"61481074190\"\n }\n }\n} ```\n## SMS Status\n\nThe `SMS_STATUS` event data is posted to you for changes to a SMS message status. Multiple status events can be triggered for a single message.\n\nThe `routed_via` field will display when a shared local number has been used to deliver your message.\n\n###### Example Payload\n\n```json {\n \"event_type\": \"SMS_STATUS\",\n \"timestamp\": \"2021-05-06T05:16:07Z\",\n \"status\": {\n \"type\": \"SMS\",\n \"id\": \"a51ebe4e-a412-440e-a8d9-464e68a521cc\",\n \"message_ref\": \"ncc5009d\",\n \"recipient\": \"447507222200\",\n \"routed_via\": \"447507333300\",\n \"sender\": \"61481074190\",\n \"status\": \"SENT\"\n }\n} ```\n## RCS Status\n\nThe `RCS_STATUS` event data is posted to you for changes to an RCS message status. RCS supports enhanced status tracking including read receipts.\n\nRCS-specific statuses include:\n\n- SENT: Submitted to the carrier.\n- DELIVERED: Delivered to handset.\n- FAILED: Failed because of an error from the carrier or handset.\n- READ: Message was read by the recipient (RCS-specific feature).\n\n###### Example Payload\n\n```json {\n \"event_type\": \"RCS_STATUS\",\n \"timestamp\": \"2025-01-07T05:16:07Z\",\n \"webhook_id\": \"fd0e6485-b905-44c1-bd55-fee1d0d6d864\",\n \"webhook_name\": \"RCS Status Webhook\",\n \"status\": {\n \"type\": \"RCS\",\n \"id\": \"6fdae71c-dad7-4c36-9734-a69693ecf3b4\",\n \"message_ref\": \"order-12345\",\n \"recipient\": \"+447903749662\",\n \"sender\": \"DemoSender\",\n \"status\": \"READ\"\n }\n} ```" paths: /v2/webhook: post: tags: - Webhook summary: Create Webhook security: - ApiKeyAuth: [] description: We use webhooks to let your application know when events happen, such as receiving an SMS message. When the event occurs, the system makes an HTTP request (usually a POST) to the URL you configured for the webhook. The request will include details of the event such as the incoming phone number or the body of an incoming message. requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/WebhookRequest' responses: '201': description: Webhook created successfully content: application/json: schema: $ref: '#/components/schemas/WebhookResponse' '400': description: Validation error content: application/json: schema: type: object properties: error: type: string example: 'Validation Error: rate_limit: greater than the maximum value of 10000' get: tags: - Webhook summary: Retrieve all webhooks security: - ApiKeyAuth: [] responses: '200': description: A list of webhooks content: application/json: schema: $ref: '#/components/schemas/WebhookListResponse' /v2/webhook/{id}: get: tags: - Webhook summary: Get a webhook by ID security: - ApiKeyAuth: [] parameters: - name: id in: path description: Unique ID of the webhook required: true schema: type: string format: uuid responses: '200': description: A single webhook content: application/json: schema: $ref: '#/components/schemas/WebhookResponse' '404': description: Webhook not found content: application/json: schema: type: object properties: error: type: string example: Webhook not found put: tags: - Webhook summary: Update Webhook description: Updates the webhook. Any fields not provided in the request body will reset to their default values. security: - ApiKeyAuth: [] parameters: - name: id in: path description: Unique identifier for the webhook required: true schema: type: string format: uuid requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/WebhookRequest' responses: '200': description: Webhook updated successfully content: application/json: schema: $ref: '#/components/schemas/WebhookResponse' '400': description: Validation error content: application/json: schema: type: object properties: error: type: string example: 'Validation Error: event_type: required' delete: tags: - Webhook summary: Delete Webhook parameters: - name: id in: path schema: type: string format: uuid required: true description: Unique ID of the webhook responses: '200': description: Webhook deletion confirmation content: application/json: schema: $ref: '#/components/schemas/WebhookDeleteResponse' '400': description: Invalid webhook ID content: application/json: schema: type: object properties: error: type: string example: invalid webhook ID '404': description: Webhook not found content: application/json: schema: type: object properties: error: type: string example: Webhook not found components: schemas: WebhookDeleteResponse: type: object description: Webhook deletion confirmation response. properties: message: type: string description: Confirmation message example: deleted required: - message EventType: type: string enum: - LINK_HIT - OPT_OUT - MMS_STATUS - SMS_INBOUND - SMS_STATUS - MMS_INBOUND - WHATSAPP_STATUS - WHATSAPP_INBOUND - RCS_STATUS - RCS_INBOUND description: 'Event type string values: - LINK_HIT: Link hit event when a recipient visits a tracked link - OPT_OUT: Opt out event when a recipient visits an opt-out link or by sending a message with the text "STOP" - MMS_STATUS: Status change for a MMS messages. Currently only comprised of internal statuses (sent, failed) - SMS_INBOUND: Inbound SMS sent from a recipient back to the sender - SMS_STATUS: Status change for a SMS message. Includes internal statuses (sent, failed) and delivery receipts (soft_bounce, hard_bounce, delivered, undelivered). Multiple status events can be triggered for a single message - MMS_INBOUND: Inbound MMS sent from a recipient back to the sender - WHATSAPP_STATUS: Status change for Whatsapp messages - WHATSAPP_INBOUND: Inbound Whatsapp sent from a recipient back to the sender - RCS_STATUS: Status change for RCS messages - RCS_INBOUND: Inbound RCS sent from a recipient back to the sender ' Filter: type: - object - 'null' description: Filter applied to webhook events properties: event_type: type: array description: Types of events to subscribe to items: $ref: '#/components/schemas/EventType' example: - SMS_STATUS - SMS_INBOUND sender: type: array description: Filter by sender items: type: string example: - '+61412345678' - '+61487654321' status: type: array description: Filter by message status (only applicable for status events) items: type: string example: - DELIVERED - FAILED message_ref: type: array description: Filter by message ref items: type: string example: - ref123 - ref456 campaign_id: type: array description: Filter by campaign ID items: type: string example: - campaign_123 - campaign_456 WebhookResponse: type: object description: Webhook details. properties: id: type: string description: Unique identifier for the webhook. example: 67e3e4af-62e8-4515-8b67-6f20d0c51ffb filter: $ref: '#/components/schemas/Filter' name: type: string description: Name of the webhook. example: Hook url: type: string description: URL (https) that accepts JSON encoded POST requests. format: uri example: https://webhook.site/uuid rate_limit: type: integer description: Rate limit for the webhook in requests per second. example: 10 is_sandbox: type: boolean deprecated: true description: Deprecated. Will be removed in a future version. example: false created_at: type: string format: date-time description: Timestamp when the webhook was created. example: '2025-04-14T00:59:32.75819Z' updated_at: type: string format: date-time description: Timestamp when the webhook was last updated. example: '2025-04-14T00:59:32.75819Z' required: - id - name - url - rate_limit - is_sandbox - created_at - updated_at WebhookListResponse: type: object description: List of webhooks response. properties: webhooks: type: array items: $ref: '#/components/schemas/WebhookResponse' WebhookRequest: type: object properties: event_type: allOf: - $ref: '#/components/schemas/EventType' description: Type of event to subscribe to. Deprecated - use filter.event_type instead. example: SMS_STATUS deprecated: true filter: type: object description: "Filter to apply to webhook events. The filters are applied differently based on the event type:\n- For status events (`SMS_STATUS`, `MMS_STATUS`, etc.): `sender`, `status`,\n `message_ref`, and `campaign_id` filters are applied to the **status** payload.\n- For `LINK_HIT` events: `sender` and `message_ref` filters are applied to\n the `source_message` in the link-hit payload.\n- For `OPT_OUT` events: `sender` and `message_ref` filters are applied to\n the `source_message` in the opt-out payload.\n- For inbound events (`SMS_INBOUND`, `MMS_INBOUND`, etc.): `sender` filter is\n applied to the `recipient` field (the sender address that received the inbound message),\n while `message_ref` and `campaign_id` filters are applied to `last_message` if available.\n\nWithin each filter array (e.g., sender, status, message_ref), the conditions are combined using an OR logic. For example, if multiple senders are specified, the webhook will trigger if the event matches any of the specified senders. Between different filters (e.g., sender and status), the conditions are combined using an AND logic. For example, the webhook will trigger only if the event matches both the specified sender and the specified status." properties: event_type: type: array description: Types of events to subscribe to items: $ref: '#/components/schemas/EventType' example: - SMS_STATUS - SMS_INBOUND sender: type: array description: Filter by sender. For outbound events (status, link-hit, opt-out), this filters by the sender of the outbound message. For inbound events, this filters by the recipient of the inbound message (the sender address that received it). items: type: string example: - '+61412345678' - '+61487654321' status: type: array description: Filter by message status (only applicable for status events) items: type: string example: - DELIVERED - FAILED message_ref: type: array description: Filter by message ref items: type: string example: - ref123 - ref456 campaign_id: type: array description: Filter by campaign ID items: type: string example: - campaign_123 - campaign_456 name: type: string description: Name of the webhook minLength: 2 maxLength: 100 example: My Webhook x-oapi-codegen-extra-tags: valid: length(2|100) url: type: string description: URL (https) that accepts JSON encoded POST requests format: uri example: https://example.com/webhook x-oapi-codegen-extra-tags: valid: required,webhook_url rate_limit: type: integer description: Rate limit for your URL in requests per second. Max 10,000/sec. If set to 0 or not specified, the default system limit will be applied. x-go-type-skip-optional-pointer: true x-oapi-codegen-extra-tags: valid: range(0|10000) is_sandbox: type: boolean deprecated: true description: Deprecated. Will be removed in a future version. x-go-type-skip-optional-pointer: true required: - name - url securitySchemes: ApiKeyAuth: type: apiKey in: header name: x-api-key description: 'All API requests require your API credentials, you will find them once logged into your account on the SETTINGS page. Scroll down to API Settings to find your API key. '