---
title: "Inbound Message"
method: POST
path: "inboundMessage"
tags: ["Callbacks"]
---

# Inbound Message

`POST inboundMessage` (webhook)

This webhook uses Telnyx headers (telnyx-timestamp, telnyx-signature-ed25519) that are compatible with Standard Webhooks specification for SDK generation. Custom validation logic can map these to standard webhook-timestamp and webhook-signature equivalents. See https://github.com/standard-webhooks/standard-webhooks for details.

## Headers

- `telnyx-timestamp` integer, required — Unix timestamp for replay attack prevention
- `telnyx-signature-ed25519` string, required — Ed25519 signature of timestamp|payload for verification

## Payload

- MessagingInboundMessageEvent
  - `data` MessagingInboundMessage0b38e7044b
    - `record_type` 'event' — Identifies the type of the resource.
    - `id` string, uuid — Identifies the type of resource.
    - `event_type` 'message.received' — The type of event being delivered.
    - `occurred_at` string, date-time — ISO 8601 formatted date indicating when the resource was created.
    - `payload` MessagingInboundMessagePayload
      - `record_type` 'message' — Identifies the type of the resource.
      - `direction` 'inbound' — The direction of the message. Inbound messages are sent to you whereas outbound messages are sent from you.
      - `id` string, uuid — Identifies the type of resource.
      - `type` 'SMS' | 'MMS' — The type of message. This value can be either 'sms' or 'mms'.
      - `messaging_profile_id` string — Unique identifier for a messaging profile.
      - `organization_id` string — Unique identifier for a messaging profile.
      - `to` object[]
        - `phone_number` string — Receiving address (+E.164 formatted phone number or short code).
        - `status` 'queued' | 'sending' | 'sent' | 'delivered' | 'sending_failed' | 'delivery_failed' | 'delivery_unconfirmed' | 'webhook_delivered'
        - `carrier` string — The carrier of the receiver.
        - `line_type` 'Wireline' | 'Wireless' | 'VoWiFi' | 'VoIP' | 'Pre-Paid Wireless' | '' — The line-type of the receiver.
      - `cc` object[]
        - `phone_number` string — Receiving address (+E.164 formatted phone number or short code).
        - `status` 'queued' | 'sending' | 'sent' | 'delivered' | 'sending_failed' | 'delivery_failed' | 'delivery_unconfirmed'
        - `carrier` string — The carrier of the receiver.
        - `line_type` 'Wireline' | 'Wireless' | 'VoWiFi' | 'VoIP' | 'Pre-Paid Wireless' | '' — The line-type of the receiver.
      - `from` object
        - `phone_number` string — Sending address (+E.164 formatted phone number, alphanumeric sender ID, or short code).
        - `status` 'received' | 'delivered'
        - `carrier` string — The carrier of the sender.
        - `line_type` 'Wireline' | 'Wireless' | 'VoWiFi' | 'VoIP' | 'Pre-Paid Wireless' | '' — The line-type of the sender.
      - `text` string — Message body (i.e., content) as a non-empty string. **Required for SMS**
      - `num_chars` integer — The number of characters in the message text
      - `subject` string, nullable — Message subject.
      - `media` object[]
        - `url` string, url — The url of the media requested to be sent.
        - `content_type` string — The MIME type of the requested media.
        - `size` integer — The size of the requested media.
        - `hash_sha256` string — The SHA256 hash of the requested media.
      - `webhook_url` string, url, nullable — The URL where webhooks related to this message will be sent.
      - `webhook_failover_url` string, url, nullable — The failover URL where webhooks related to this message will be sent if sending to the primary URL fails.
      - `encoding` string — Encoding scheme used for the message body.
      - `parts` integer — Number of parts into which the message's body must be split.
      - `tags` string[] — Tags associated with the resource.
      - `cost` object, nullable
        - `amount` string — The amount deducted from your account.
        - `currency` string — The ISO 4217 currency identifier.
      - `cost_breakdown` object, nullable — Detailed breakdown of the message cost components.
        - `carrier_fee` object
          - `amount` string — The carrier fee amount.
          - `currency` string — The ISO 4217 currency identifier.
        - `rate` object
          - `amount` string — The rate amount applied.
          - `currency` string — The ISO 4217 currency identifier.
      - `tcr_campaign_id` string, nullable — The Campaign Registry (TCR) campaign ID associated with the message.
      - `tcr_campaign_billable` boolean — Indicates whether the TCR campaign is billable.
      - `tcr_campaign_registered` string, nullable — The registration status of the TCR campaign.
      - `received_at` string, date-time — ISO 8601 formatted date indicating when the message request was received.
      - `sent_at` string, date-time, nullable — Not used for inbound messages.
      - `completed_at` string, date-time, nullable — Not used for inbound messages.
      - `valid_until` string, date-time, nullable — Not used for inbound messages.
      - `errors` MessagingError0b38e7044b[] — These errors may point at addressees when referring to unsuccessful/unconfirmed delivery statuses.
        - `code` string, required
        - `title` string, required
        - `detail` string
        - `source` object
          - `pointer` string, json-pointer — JSON pointer (RFC6901) to the offending entity.
          - `parameter` string — Indicates which query parameter caused the error.
        - `meta` object

## Acknowledgement `200`

The server must return an HTTP 200, otherwise we will reattempt delivery at the failover webhook URL.

---

[API](https://skmtc.net/team-telnyx/apis/telnyx-api-2.md) · [All operations](https://skmtc.net/team-telnyx/apis/telnyx-api-2/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/team-telnyx/telnyx-api-2/versions/8f5f4e537994/schema)