Channels

SMS

Send and receive SMS, and MMS where supported, through your own Twilio phone number.

Requirements#

A Twilio account.
A Twilio phone number with SMS capability, registered for the destinations you send to (for example A2P 10DLC registration for the United States).
The account SID and auth token, and the SID of the phone number.

Connect the channel#

Paste the credentials in the console, or post them to POST /v1/channels with type: "sms". The identifier is the Twilio phone number in E.164 format.

Field	Where to find it
`account_sid`	Twilio account SID, starting with `AC`. Shown on the Twilio console dashboard.
`phone_number_sid`	SID of the phone number, starting with `PN`. Shown in the properties of the number.
`auth_token`	Twilio auth token, shown next to the account SID.

curl https://api.omnimessage.co/v1/channels \
  -H "Authorization: Bearer om_live_xxxxxxxxxxxxxxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "type": "sms",
    "name": "Transactional SMS",
    "identifier": "+14155550123",
    "credentials": {
      "account_sid": "AC...",
      "phone_number_sid": "PN...",
      "auth_token": "..."
    }
  }'

Recipients#

to is the mobile number of the recipient in E.164 format, for example +14155550199.

Supported message types#

Type	Use it for
`text`	Plain text of up to 4096 characters.
`attachments`	One image, video, document, audio file, voice note or sticker, fetched from an HTTPS URL.

Channel rules#

Text longer than one SMS segment (160 GSM-7 characters, or 70 when the text contains characters outside GSM-7) is split into segments by the carrier network. Twilio bills per segment; OmniMessage bills one message per API message.
attachments is sent as MMS. It works only if the sending number and the destination country and carrier support MMS; otherwise the message fails and is refunded.
Sender registration, opt-out keywords such as STOP and content rules are enforced by Twilio and the carriers. A recipient who opted out cannot be messaged again until they opt back in.
Replies to your number arrive as message.received events.

Example request#

curl https://api.omnimessage.co/v1/messages \
  -H "Authorization: Bearer om_live_xxxxxxxxxxxxxxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "channel": "ch_5vB8nM1kL4jH7fD0sA3g",
    "to": "+14155550199",
    "type": "text",
    "text": {
      "body": "Acme: your parcel arrives today between 10:00 and 12:00."
    }
  }'

Delivery statuses#

A message reaches sent when the carrier network accepts it. delivered is reported only where the destination carrier returns delivery receipts, so many messages end at sent. SMS has no read receipts.

Pricing#

Each accepted outbound message on a sms channel consumes one package credit or the sms price from the wallet. Read your effective price from GET /v1/pricing. Inbound messages are free. Fees charged by the provider are separate. See Billing.