Telnyx

Authorizations

Authorization

string

header

required

Bearer authentication header of the form Bearer <token>, where <token> is your auth token.

Headers

telnyx-timestamp

integer<int64>

required

Unix timestamp (seconds since epoch) of when the webhook was sent - compatible with webhook-timestamp Unix timestamp for replay attack prevention

telnyx-signature-ed25519

string

required

Base64 encoded Ed25519 signature for webhook verification - compatible with webhook-signature Ed25519 signature of timestamp|payload for verification

Body

application/json

data

object

Show child attributes

data.record_type

enum<string>

Identifies the type of the resource.

Available options:

event

Example:

"event"

data.id

string<uuid>

Identifies the type of resource.

data.event_type

enum<string>

The type of event being delivered.

Available options:

message.received

Example:

"message.received"

data.occurred_at

string<date-time>

ISO 8601 formatted date indicating when the resource was created.

data.payload

object

Show child attributes

data.payload.record_type

enum<string>

Identifies the type of the resource.

Available options:

message

Example:

"message"

data.payload.direction

enum<string>

The direction of the message. Inbound messages are sent to you whereas outbound messages are sent from you.

Available options:

inbound

Example:

"inbound"

data.payload.id

string<uuid>

Identifies the type of resource.

data.payload.type

enum<string>

The type of message. This value can be either 'sms' or 'mms'.

Available options:

SMS,

MMS

data.payload.messaging_profile_id

string

Unique identifier for a messaging profile.

data.payload.to

object[]

Show child attributes

data.payload.to.phone_number

string<address>

Receiving address (+E.164 formatted phone number or short code).

data.payload.to.status

enum<string>

Available options:

queued,

sending,

sent,

delivered,

sending_failed,

delivery_failed,

delivery_unconfirmed,

webhook_delivered

data.payload.to.carrier

string

The carrier of the receiver.

data.payload.to.line_type

enum<string>

The line-type of the receiver.

Available options:

Wireline,

Wireless,

VoWiFi,

VoIP,

Pre-Paid Wireless,

data.payload.cc

object[]

Show child attributes

data.payload.cc.phone_number

string<address>

Receiving address (+E.164 formatted phone number or short code).

data.payload.cc.status

enum<string>

Available options:

queued,

sending,

sent,

delivered,

sending_failed,

delivery_failed,

delivery_unconfirmed

data.payload.cc.carrier

string

The carrier of the receiver.

data.payload.cc.line_type

enum<string>

The line-type of the receiver.

Available options:

Wireline,

Wireless,

VoWiFi,

VoIP,

Pre-Paid Wireless,

data.payload.from

object

Show child attributes

data.payload.from.phone_number

string<address>

Sending address (+E.164 formatted phone number, alphanumeric sender ID, or short code).

data.payload.from.status

enum<string>

Available options:

received,

delivered

data.payload.from.carrier

string

The carrier of the sender.

data.payload.from.line_type

enum<string>

The line-type of the sender.

Available options:

Wireline,

Wireless,

VoWiFi,

VoIP,

Pre-Paid Wireless,

data.payload.text

string

Message body (i.e., content) as a non-empty string.

Required for SMS

data.payload.media

object[]

Show child attributes

data.payload.media.url

string<url>

The url of the media requested to be sent.

data.payload.media.content_type

string<mime-type>

The MIME type of the requested media.

data.payload.media.size

integer

The size of the requested media.

data.payload.media.hash_sha256

string

The SHA256 hash of the requested media.

Required string length: 32

data.payload.webhook_url

string<url> | null

The URL where webhooks related to this message will be sent.

data.payload.webhook_failover_url

string<url> | null

The failover URL where webhooks related to this message will be sent if sending to the primary URL fails.

data.payload.encoding

string

Encoding scheme used for the message body.

data.payload.parts

integer

Number of parts into which the message's body must be split.

Required range: 1 <= x <= 10

data.payload.tags

string[]

Tags associated with the resource.

data.payload.cost

object

Show child attributes

data.payload.cost.amount

string<decimal>

The amount deducted from your account.

data.payload.cost.currency

string<iso4217>

The ISO 4217 currency identifier.

data.payload.cost_breakdown

object

Detailed breakdown of the message cost components.

Show child attributes

data.payload.cost_breakdown.carrier_fee

object

Show child attributes

data.payload.cost_breakdown.carrier_fee.amount

string<decimal>

The carrier fee amount.

data.payload.cost_breakdown.carrier_fee.currency

string<iso4217>

The ISO 4217 currency identifier.

data.payload.cost_breakdown.rate

object

Show child attributes

data.payload.cost_breakdown.rate.amount

string<decimal>

The rate amount applied.

data.payload.cost_breakdown.rate.currency

string<iso4217>

The ISO 4217 currency identifier.

data.payload.tcr_campaign_id

string | null

The Campaign Registry (TCR) campaign ID associated with the message.

data.payload.tcr_campaign_billable

boolean

Indicates whether the TCR campaign is billable.

data.payload.tcr_campaign_registered

string | null

The registration status of the TCR campaign.

Example:

"REGISTERED"

data.payload.received_at

string<date-time>

ISO 8601 formatted date indicating when the message request was received.

data.payload.sent_at

string<date-time> | null

Not used for inbound messages.

data.payload.completed_at

string<date-time> | null

Not used for inbound messages.

data.payload.valid_until

string<date-time> | null

Not used for inbound messages.

data.payload.errors

object[]

These errors may point at addressees when referring to unsuccessful/unconfirmed delivery statuses.

Show child attributes

data.payload.errors.code

string<integer>

required

data.payload.errors.title

string

required

data.payload.errors.detail

string

data.payload.errors.source

object

Show child attributes

data.payload.errors.source.pointer

string<json-pointer>

JSON pointer (RFC6901) to the offending entity.

data.payload.errors.source.parameter

string

Indicates which query parameter caused the error.

data.payload.errors.meta

object

Example:

{
  "record_type": "message",
  "direction": "inbound",
  "id": "7ee4241c-f127-47e5-9c34-3aac291f8058",
  "type": "SMS",
  "messaging_profile_id": "0f512bda-ae1e-4597-8e11-e5f5686b97d3",
  "organization_id": "b448f9cc-a842-4784-98e9-03c1a5872950",
  "from": {
    "phone_number": "+18665550001",
    "status": "delivered",
    "carrier": "T-MOBILE USA, INC.",
    "line_type": "Wireless"
  },
  "to": [
    {
      "phone_number": "+18445550001",
      "status": "delivered",
      "carrier": "TELNYX LLC",
      "line_type": "VoIP"
    }
  ],
  "cc": [],
  "text": "Hello, World!",
  "subject": "From Telnyx!",
  "media": [],
  "webhook_url": "https://www.example.com/hooks",
  "webhook_failover_url": "https://backup.example.com/hooks",
  "encoding": "GSM-7",
  "parts": 1,
  "tags": ["Greetings"],
  "cost": { "amount": 0.0051, "currency": "USD" },
  "cost_breakdown": {
    "carrier_fee": { "amount": 0.00305, "currency": "USD" },
    "rate": { "amount": 0.00205, "currency": "USD" }
  },
  "tcr_campaign_id": "TCPA3X7",
  "tcr_campaign_billable": true,
  "tcr_campaign_registered": "REGISTERED",
  "received_at": "2019-01-23T18:10:02.574Z",
  "sent_at": null,
  "completed_at": null,
  "valid_until": null,
  "errors": []
}

Example:

{
  "record_type": "event",
  "id": "bf6307bd-884d-4c1f-b6ea-c62b8c495d3c",
  "event_type": "message.received",
  "occurred_at": "date-time",
  "payload": {
    "record_type": "message",
    "direction": "inbound",
    "id": "7ee4241c-f127-47e5-9c34-3aac291f8058",
    "type": "SMS",
    "messaging_profile_id": "0f512bda-ae1e-4597-8e11-e5f5686b97d3",
    "organization_id": "b448f9cc-a842-4784-98e9-03c1a5872950",
    "from": {
      "phone_number": "+18665550001",
      "carrier": "T-MOBILE USA, INC.",
      "line_type": "Wireless"
    },
    "to": [
      {
        "phone_number": "+18445550001",
        "status": "delivered",
        "carrier": "TELNYX LLC",
        "line_type": "VoIP"
      }
    ],
    "cc": [],
    "text": "Hello, World!",
    "subject": "From Telnyx!",
    "media": [],
    "webhook_url": "https://www.example.com/hooks",
    "webhook_failover_url": "https://backup.example.com/hooks",
    "encoding": "GSM-7",
    "parts": 1,
    "tags": ["Greetings"],
    "cost": { "amount": 0.0051, "currency": "USD" },
    "cost_breakdown": {
      "carrier_fee": { "amount": 0.00305, "currency": "USD" },
      "rate": { "amount": 0.00205, "currency": "USD" }
    },
    "tcr_campaign_id": "TCPA3X7",
    "tcr_campaign_billable": true,
    "tcr_campaign_registered": "REGISTERED",
    "received_at": "2019-01-23T18:10:02.574Z",
    "sent_at": null,
    "completed_at": null,
    "valid_until": null,
    "errors": []
  }
}

Response

200

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

OAuth Discovery

IP Addresses

IP Ranges

SIM Cards

Addresses

Advanced Number Orders

Assistants

Audio

Chat

Clusters

Conversations

Embeddings

Fine Tuning

Integrations

MCP Servers

Audit Logs

Authentication Providers

Phone Number Search

Billing

Billing Groups

Brands

SIM Card Actions

Bundles

User Bundles

Call Control Applications

Debugging

Call Commands

Call Information

Campaign

Voice Channels

API Reference

Phone Number Orders

Conference Commands

Connections

Country Coverage

Credential Connections

Call Recordings

Customer Service Record

Detail Records

Dialogflow Integration

Documents

Dynamic Emergency Addresses

Dynamic Emergency Endpoints

Enum

External Connections

Programmable Fax Applications

Programmable Fax Commands

FQDN Connections

FQDNs

Global IPs

Inexplicit Number Orders

Integration Secrets

Inventory Level

IP Connections

IPs

Reports

MDR Detailed Reports

Speech to Text Batch Reports

CDR Reports

MDR Usage Reports

Telco Data Usage Reports

Speech to text Usage Reports

CDR Usage Reports

Managed Accounts

Media Storage API

Messages

RCS messaging

Messaging Hosted Number

Number Configurations

Advanced OptIn/OptOut

Messaging Profiles

Messaging Tollfree Verification

Messaging URL Domains

Mobile Network Operators

Push Credentials

Coverage

Networks

Notifications

Phone Number Block Orders

Number Lookup