SMS OTP

Requirements#

• An OTP SMS route with an approved sender ID.
• The API key of that route.

Connect the channel#

Paste the key in the console, or post it to POST /v1/channels with type: "sms_otp". The identifier is the sender ID that recipients see, for example ACME.

curl https://api.omnimessage.co/v1/channels \
  -H "Authorization: Bearer om_live_xxxxxxxxxxxxxxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "type": "sms_otp",
    "name": "Login codes",
    "identifier": "ACME",
    "credentials": {
      "api_key": "..."
    }
  }'

Recipients#

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

Supported message types#

Channel rules#

• Only text is supported. Attachments and interactive types are rejected with 400 unsupported_message_type.
• Use this channel for verification codes only. Keep the text short, state what the code is for and how long it is valid, and send nothing promotional.
• Generate and verify the code in your own system. OmniMessage delivers the text you provide; it does not create or check codes.
• Send an Idempotency-Key per verification attempt, so that a retried request cannot deliver two different codes.
• The route is one-way. Do not ask recipients to reply.

Example request#

curl https://api.omnimessage.co/v1/messages \
  -H "Authorization: Bearer om_live_xxxxxxxxxxxxxxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "channel": "ch_8nM1kL4jH7fD0sA3gB6v",
    "to": "+905321234567",
    "type": "text",
    "text": {
      "body": "Your Acme verification code is 482910. It expires in 5 minutes."
    }
  }'

Delivery statuses#

A message reaches sent when the route accepts it and delivered where the destination carrier returns a delivery receipt. There are no read receipts. Start your code expiry timer when you send, not when the message is delivered.

Pricing#

Each accepted outbound message on a sms_otp channel consumes one package credit or the sms_otp 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.