Telnyx

Authorizations

Authorization

string

header

required

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

Body

application/json

Message payload

string<address>

required

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

Example:

"+E.164"

from

string<address>

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

Required if sending with a phone number, short code, or alphanumeric sender ID.

messaging_profile_id

string

Unique identifier for a messaging profile.

Required if sending via number pool or with an alphanumeric sender ID.

text

string

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

Required for SMS

subject

string

Subject of multimedia message

media_urls

string<url>[]

A list of media URLs. The total media size must be less than 1 MB.

Required for MMS

webhook_url

string<url>

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

webhook_failover_url

string<url>

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

use_profile_webhooks

boolean

default:true

If the profile this number is associated with has webhooks, use them for delivery notifications. If webhooks are also specified on the message itself, they will be attempted first, then those on the profile.

type

enum<string>

The protocol for sending the message, either SMS or MMS.

Available options:

SMS,

MMS

auto_detect

boolean

default:false

Automatically detect if an SMS message is unusually long and exceeds a recommended limit of message parts.

send_at

string<date-time> | null

ISO 8601 formatted date indicating when to send the message - accurate up till a minute.

Response

Successful response with details about a message.

data

object

Show child attributes

data.record_type

enum<string>

Identifies the type of the resource.

Available options:

message

Example:

"message"

data.direction

enum<string>

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

Available options:

outbound

Example:

"outbound"

data.id

string<uuid>

Identifies the type of resource.

data.type

enum<string>

The type of message.

Available options:

SMS,

MMS

data.messaging_profile_id

string

Unique identifier for a messaging profile.

data.organization_id

string<uuid>

The id of the organization the messaging profile belongs to.

data.from

object

Show child attributes

data.from.phone_number

string<address>

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

data.from.carrier

string

The carrier of the receiver.

data.from.line_type

enum<string>

The line-type of the receiver.

Available options:

Wireline,

Wireless,

VoWiFi,

VoIP,

Pre-Paid Wireless,

data.to

object[]

Show child attributes

data.to.phone_number

string<address>

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

data.to.status

enum<string>

The delivery status of the message.

Available options:

queued,

sending,

sent,

expired,

sending_failed,

delivery_unconfirmed,

delivered,

delivery_failed

data.to.carrier

string

The carrier of the receiver.

data.to.line_type

enum<string>

The line-type of the receiver.

Available options:

Wireline,

Wireless,

VoWiFi,

VoIP,

Pre-Paid Wireless,

data.cc

object[]

Show child attributes

data.cc.phone_number

string<address>

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

data.cc.status

enum<string>

Available options:

queued,

sending,

sent,

delivered,

sending_failed,

delivery_failed,

delivery_unconfirmed

data.cc.carrier

string

The carrier of the receiver.

data.cc.line_type

enum<string>

The line-type of the receiver.

Available options:

Wireline,

Wireless,

VoWiFi,

VoIP,

Pre-Paid Wireless,

data.text

string

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

Required for SMS

data.subject

string | null

Subject of multimedia message

data.media

object[]

Show child attributes

data.media.url

string<url>

The url of the media requested to be sent.

data.media.content_type

string<mime-type> | null

The MIME type of the requested media.

data.media.sha256

string | null

The SHA256 hash of the requested media.

data.media.size

integer | null

The size of the requested media.

data.webhook_url

string<url> | null

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

data.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.encoding

string

Encoding scheme used for the message body.

data.parts

integer

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

Required range: 1 <= x <= 10

data.tags

string[]

Tags associated with the resource.

data.cost

object

Show child attributes

data.cost.amount

string<decimal>

The amount deducted from your account.

data.cost.currency

string<iso4217>

The ISO 4217 currency identifier.

data.cost_breakdown

object

Detailed breakdown of the message cost components.

Show child attributes

data.cost_breakdown.carrier_fee

object

Show child attributes

data.cost_breakdown.carrier_fee.amount

string<decimal>

The carrier fee amount.

data.cost_breakdown.carrier_fee.currency

string<iso4217>

The ISO 4217 currency identifier.

data.cost_breakdown.rate

object

Show child attributes

data.cost_breakdown.rate.amount

string<decimal>

The rate amount applied.

data.cost_breakdown.rate.currency

string<iso4217>

The ISO 4217 currency identifier.

data.tcr_campaign_id

string | null

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

data.tcr_campaign_billable

boolean

Indicates whether the TCR campaign is billable.

data.tcr_campaign_registered

string | null

The registration status of the TCR campaign.

Example:

"REGISTERED"

data.received_at

string<date-time>

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

data.sent_at

string<date-time> | null

ISO 8601 formatted date indicating when the message was sent.

data.completed_at

string<date-time> | null

ISO 8601 formatted date indicating when the message was finalized.

data.valid_until

string<date-time> | null

Message must be out of the queue by this time or else it will be discarded and marked as 'sending_failed'. Once the message moves out of the queue, this field will be nulled

data.errors

object[]

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

Show child attributes

data.errors.code

string<integer>

required

data.errors.title

string

required

data.errors.detail

string

data.errors.source

object

Show child attributes

data.errors.source.pointer

string<json-pointer>

JSON pointer (RFC6901) to the offending entity.

data.errors.source.parameter

string

Indicates which query parameter caused the error.

data.errors.meta

object

Example:

{
  "record_type": "message",
  "direction": "outbound",
  "id": "40385f64-5717-4562-b3fc-2c963f66afa6",
  "type": "MMS",
  "messaging_profile_id": "4000eba1-a0c0-4563-9925-b25e842a7cb6",
  "organization_id": "b448f9cc-a842-4784-98e9-03c1a5872950",
  "from": {
    "phone_number": "+18445550001",
    "carrier": "TELNYX LLC",
    "line_type": "VoIP"
  },
  "to": [
    {
      "phone_number": "+18665550001",
      "status": "queued",
      "carrier": "T-MOBILE USA, INC.",
      "line_type": "Wireless"
    }
  ],
  "cc": [],
  "text": "Hello, World!",
  "subject": "From Telnyx!",
  "media": [
    {
      "url": "https://pbs.twimg.com/profile_images/1142168442042118144/AW3F4fFD_400x400.png",
      "content_type": null,
      "sha256": null,
      "size": null
    }
  ],
  "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": []
}

AI

Real-Time Communications

WebRTC

Messaging

Identity

Storage & Data

Account & Billing

Other Products

SETI

OAuth

Send a message

Authorizations

Body

Response