API docs by Redocly

SMS API (1.5.1)

Download OpenAPI specification:

Vonage DevRel: devrel@vonage.com URL: https://developer.vonage.com/

With the SMS API you can send SMS from your account and lookup messages both messages that you've sent as well as messages sent to your virtual numbers. Numbers are specified in E.164 format. More SMS API documentation is at https://developer.vonage.com/messaging/sms/overview

Send an SMS

Send an outbound SMS from your Vonage account

Authorizations:
basicAuth
path Parameters
format
required
string
Default: "json"
Enum: "json" "xml"
Example: json

The format of the response

Request Body schema: application/x-www-form-urlencoded
required
api_key
string = 8 characters

Your API key. Only required if setting sig.

sig
string [ 16 .. 60 ] characters

The hash of the request parameters in alphabetical order, a timestamp and the signature secret. See Signing Requests for more details. Note: DO NOT set an Authorization header when using sig.

timestamp
integer

An integer containing the number of seconds since the epoch (this is sometimes also known as UNIX time). Only required if setting sig. See Signing Requests for more details.

from
required
string

The name or number the message should be sent from. Alphanumeric senderID's are not supported in all countries, see Global Messaging for more details. If alphanumeric, spaces will be ignored. Numbers are specified in E.164 format.

to
required
string [ 7 .. 15 ] characters \d{7,15}

The number that the message should be sent to. Numbers are specified in E.164 format.

text
required
string

The body of the message being sent. If your message contains characters that can be encoded according to the GSM Standard and Extended tables then you can set the type to text. If your message contains characters outside this range, then you will need to set the type to unicode.

ttl
integer [ 20000 .. 604800000 ]
Default: 259200000

Advanced: The duration in milliseconds the delivery of an SMS will be attempted. By default Vonage attempts delivery for 72 hours, however the maximum effective value depends on the operator and is typically 24 - 48 hours. We recommend this value should be kept at its default or at least 30 minutes.

status-report-req
boolean
Default: true

Advanced: Boolean indicating if you like to receive a Delivery Receipt.

callback
string

Advanced: The webhook endpoint the delivery receipt for this sms is sent to. This parameter overrides the webhook endpoint you set in Dashboard. Max 100 characters.

message-class
integer
Enum: 0 1 2 3

Advanced: The Data Coding Scheme value of the message

type
string
Default: "text"
Enum: "text" "binary" "unicode"

Advanced: The format of the message body

body
string

Advanced: Hex encoded binary data. Depends on type parameter having the value binary.

udh
string

Advanced: Your custom Hex encoded User Data Header. Depends on type parameter having the value binary.

protocol-id
integer

Advanced: The value of the protocol identifier to use. Ensure that the value is aligned with udh.

client-ref
string

Advanced: You can optionally include your own reference of up to 100 characters.

account-ref
string

Advanced: An optional string used to identify separate accounts using the SMS endpoint for billing purposes. To use this feature, please email support

entity-id
string

Advanced: A string parameter that satisfies regulatory requirements when sending an SMS to specific countries. For more information please refer to the Country-Specific Outbound SMS Features

content-id
string

Advanced: A string parameter that satisfies regulatory requirements when sending an SMS to specific countries. For more information please refer to the Country-Specific Outbound SMS Features

trusted-number
boolean
Default: false

Setting this parameter to true overrides, on a per-message basis, any protections set up via Fraud Defender (Traffic Rules, SMS Burst Protection, AIT Protection).

This parameter only has any effect for accounts subscribed to Fraud Defender Premium.

pool-id
string

The ID of the Number Pool to use as the sender of this message. If specified, a number from the pool will be used as the from number. The from parameter is still required even when specifying a pool-id and will be used as a fall-back if the number pool cannot be used. See the Number Pools documentation for more information.

Responses

Callbacks

Response samples

Content type
Example
{
  • "message-count": "1",
  • "messages": [
    ]
}

Callback payload samples

Callback
POST: Delivery Receipt
Content type
application/json
{
  • "msisdn": "447700900000",
  • "to": "AcmeInc",
  • "network-code": "12345",
  • "messageId": "0A0000001234567B",
  • "price": "0.03330000",
  • "status": "delivered",
  • "scts": "2001011400",
  • "err-code": "0",
  • "api-key": "abcd1234",
  • "message-timestamp": "2020-01-01 12:00:00",
  • "client-ref": "my-personal-reference"
}