SMS API

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

Télécharger la spécification OpenAPI

Opérations disponibles

Send an SMS

Send an SMS

Send an outbound SMS from your Vonage account

posthttps://rest.nexmo.com/sms/:format

Authentification

Clé	Description	Où	Exemple
Authorization	Clé et secret de l'API encodés en Base64 et reliés par deux points. En savoir plus	Headers	`Basic <base64>`

Trajectoire Paramètres

format

string

Exigée

Défautjson

exemplejson

The format of the response

Il doit s'agir de l'un d'entre eux :jsonxml

Corps de la demande
Type de contenu
application/x-www-form-urlencoded

api_key

string

Min8

Max8

exempleabcd1234

Your API key. Only required if setting sig.

sig

string

Min16

Max60

exemple5d41402abc4b2a76b9719d911017c592

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

exemple1617187200

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

string

Exigée

exempleAcmeInc

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.

string

Exigée

Min7

Max15

exemple447700900000

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

text

string

Exigée

exempleHello World!

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

Min20000

Max604800000

Défaut259200000

exemple900000

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

Défauttrue

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

callback

string

exemplehttps://example.com/sms-dlr

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

Advanced: The Data Coding Scheme value of the message

Il doit s'agir de l'un d'entre eux :0123

type

string

Défauttext

exempletext

Advanced: The format of the message body

Il doit s'agir de l'un d'entre eux :textbinaryunicode

body

string

exemple0011223344556677

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

udh

string

exemple06050415811581

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

protocol-id

integer

exemple127

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

client-ref

string

exemplemy-personal-reference

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

account-ref

string

exemplecustomer1234

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

exemple1101456324675322134

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

exemple1107457532145798767

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

exempletrue

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

exempleabc123

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.

Exemple Demande

POST /sms/:format HTTP/1.1
Host: rest.nexmo.com
Content-Type: application/x-www-form-urlencoded
Content-Length: 430

api_key=abcd1234&sig=5d41402abc4b2a76b9719d911017c592&timestamp=1617187200&from=AcmeInc&to=447700900000&text=Hello+World!&ttl=900000&status-report-req=false&callback=https://example.com/sms-dlr&message-class=0&type=text&body=0011223344556677&udh=06050415811581&protocol-id=127&client-ref=my-personal-reference&account-ref=customer1234&entity-id=1101456324675322134&content-id=1107457532145798767&trusted-number=true&pool-id=abc123

POST /sms/:format HTTP/1.1
Host: rest.nexmo.com
Content-Type: application/x-www-form-urlencoded
Content-Length: 430

api_key=abcd1234&sig=5d41402abc4b2a76b9719d911017c592&timestamp=1617187200&from=AcmeInc&to=447700900000&text=Hello+World!&ttl=900000&status-report-req=false&callback=https://example.com/sms-dlr&message-class=0&type=text&body=0011223344556677&udh=06050415811581&protocol-id=127&client-ref=my-personal-reference&account-ref=customer1234&entity-id=1101456324675322134&content-id=1107457532145798767&trusted-number=true&pool-id=abc123

Réponses
Type de contenu
application/json

Success

L'un des

message-count

string

exemple1

The amount of messages in the request

messages

array

string

exemple447700900000

The number the message was sent to. Numbers are specified in E.164 format.

message-id

string

exempleaaaaaaaa-bbbb-cccc-dddd-0123456789ab

The ID of the message

status

string

exemple0

The status of the message. See Troubleshooting Failed SMS.

remaining-balance

string

exemple3.14159265

Your estimated remaining balance

message-price

string

exemple0.03330000

The estimated cost of the message

network

string

exemple12345

The estimated ID of the network of the recipient

client-ref

string

exemplemy-personal-reference

If a client-ref was included when sending the SMS, this field will be included and hold the value that was sent.

account-ref

string

exemplecustomer1234

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

Exemple Réponse»Message sent

{
   "message-count": "1",
   "messages": [
      {
         "to": "447700900000",
         "message-id": "aaaaaaaa-bbbb-cccc-dddd-0123456789ab",
         "status": "0",
         "remaining-balance": "3.14159265",
         "message-price": "0.03330000",
         "network": "12345",
         "client-ref": "my-personal-reference",
         "account-ref": "customer1234"
      }
   ]
}

Delivery Receipt callback

The following are parameters sent in as a delivery receipt callback. You can subscribe to webhooks to receive notification when the delivery status of an SMS that you have sent with Vonage changes.

posthttps://example.com/webhooks/event

Corps de la demande
Type de contenu
application/json

msisdn

string

exemple447700900000

The number the message was sent to. Numbers are specified in E.164 format.

string

exempleAcmeInc

The SenderID you set in from in your request.

network-code

string

exemple12345

The Mobile Country Code Mobile Network Code (MCCMNC) of the carrier this phone number is registered with.

messageId

string

exemple0A0000001234567B

The Vonage ID for this message.

price

string

exemple0.03330000

The cost of the message

status

string

exempledelivered

A code that explains where the message is in the delivery process.

scts

string

exemple2001011400

When the DLR was received from the carrier in the following format YYMMDDHHMM. For example, 2001011400 is at 2020-01-01 14:00

err-code

string

exemple0

The status of the request. Will be a non 0 value if there has been an error, or if the status is unknown. See the Delivery Receipt documentation for more details

api-key

string

exempleabcd1234

The API key that sent the SMS. This is useful when multiple accounts are sending webhooks to the same endpoint.

message-timestamp

string

exemple2020-01-01 12:00:00

The time when Vonage started to push this Delivery Receipt to your webhook endpoint.

Exemple Charge utile

{
   "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"
}

Réponses

Your server returns this code if it accepts the callback

Crochets Web

Les webhooks sont une extension d'une API, mais au lieu que votre code demande des données, l'API vous envoie des données. Les données arrivent dans une requête web à votre application.

Pour en savoir plus sur les webhooks, consultez notre site documentation sur les webhooks.

Cette API peut envoyer l'un des webhooks décrits ci-dessous à l'URL que vous avez configurée. Vous devez répondre avec une réponse HTTP 200 ou 204, sinon les demandes seront relancées.

Opérations disponibles

Inbound SMS

Inbound SMS webhook

If you rent one or more virtual numbers from Vonage, inbound messages to that number are sent to your webhook endpoint.

When you receive an inbound message, you must send a 2xx response. If you do not send a 2xx response Vonage will resend the inbound message for the next 24 hours.

posthttps://example.com/webhooks/inbound-sms

Corps de la demande
Type de contenu
application/json

api-key

string

Exigée

exempleabcd1234

The Vonage API Key of the receiving account.

msisdn

string

Exigée

exemple447700900001

The phone number that this inbound message was sent from. Numbers are specified in E.164 format.

string

Exigée

exemple447700900000

The phone number the message was sent to. This is your virtual number. Numbers are specified in E.164 format.

messageId

string

Exigée

exempleaaaaaaaa-bbbb-cccc-dddd-0123456789ab

The ID of the message

text

string

Exigée

exempleHello world

The message body for this inbound message.

type

string

Exigée

exempletext

Possible values are:

text - standard text.
unicode - URLencoded unicode . This is valid for standard GSM, Arabic, Chinese, double-encoded characters and so on.
binary - a binary message.

keyword

string

Exigée

exempleHELLO

The first word in the message body. Converted to upper case.

message-timestamp

string

Exigée

exemple{}

The time when Vonage started to push this Delivery Receipt to your webhook endpoint.

timestamp

string

exemple1578787200

A unix timestamp representation of message-timestamp.

nonce

string

exempleaaaaaaaa-bbbb-cccc-dddd-0123456789ab

A random string that forms part of the signed set of parameters, it adds an extra element of unpredictability into the signature for the request. You use the nonce and timestamp parameters with your shared secret to calculate and validate the signature for inbound messages.

concat

string

exempletrue

True - if this is a concatenated message. This field does not exist if it is a single message

concat-ref

string

exemple1

The transaction reference. All parts of this message share this value.

concat-total

string

exemple3

The number of parts in this concatenated message.

concat-part

string

exemple2

The number of this part in the message. Counting starts at 1.

data

string(binary)

The content of this message, if type is binary.

udh

string

The hex encoded User Data Header, if type is binary

Exemple Charge utile

{
   "api-key": "abcd1234",
   "msisdn": "447700900001",
   "to": "447700900000",
   "messageId": "aaaaaaaa-bbbb-cccc-dddd-0123456789ab",
   "text": "Hello world",
   "type": "text",
   "keyword": "HELLO",
   "message-timestamp": {},
   "timestamp": "1578787200",
   "nonce": "aaaaaaaa-bbbb-cccc-dddd-0123456789ab",
   "concat": "true",
   "concat-ref": "1",
   "concat-total": "3",
   "concat-part": "2",
   "data": "string",
   "udh": "string"
}

Réponses

Your server returns this code if it accepts the callback

Erreurs

Voici une liste non exhaustive des codes d'erreur susceptibles de se produire lors de l'utilisation de cette API.

Ces codes s'ajoutent à ceux de notre site codes d'erreur génériques.

Code	Informations
1	Description Throttled. You are sending SMS faster than the account limit. Résolution Refer to What is the Throughput Limit for Outbound SMS? for more information.
2	Description Missing Parameters. Your request is missing one of the required parameters `from`, `to`, `api_key`, `api_secret` or `text`. Résolution Check your parameters and try again.
3	Description Invalid Parameters. The value of one or more parameters is invalid. Résolution Check your parameters and try again.
4	Description Invalid Credentials. Your API key and/or secret are incorrect, invalid or disabled. Résolution Visit the Dashboard and check your credentials.
5	Description Internal Error. An error has occurred in the platform whilst processing this message. Résolution If the error persists, contact support.
6	Description Invalid Message. The platform was unable to process this message, for example, an un-recognized number prefix. Résolution N/A
7	Description Number Barred. The number you are trying to send messages to is blacklisted and may not receive them. Résolution N/A
8	Description Partner Account Barred. Your Vonage account has been suspended. Résolution Contact support.
9	Description Partner Quota Violation. You do not have sufficient credit to send the message. Résolution Top-up and retry.
10	Description Too Many Existing Binds. The number of simultaneous connections to the platform exceeds your account allocation. Résolution Back-off and retry.
11	Description Account Not Enabled For HTTP. This account is not provisioned for the SMS API. Résolution This error usually indicates that you should use SMPP instead.
12	Description Message Too Long. The message length exceeds the maximum allowed. Résolution Send shorter messages.
14	Description Invalid Signature. The signature supplied could not be verified. Résolution Check the documentation for signing messages or use one of the SDKs to handle the signing.
15	Description Invalid Sender Address. You are using a non-authorized sender ID in the `from` field. Résolution This is most commonly seen in North America, where a Vonage long virtual number or short code is required.
17	Description Message Blocked by Provider. The messaging provider has chosen to block this message. This may be due to content or restrictions imposed by the provider. Résolution N/A
22	Description Invalid Network Code. The network code supplied was either not recognized, or does not match the country of the destination address. Résolution Check the network code or remove it from your request.
23	Description Invalid Callback Url. The callback URL supplied was either too long or contained illegal characters. Résolution Supply a valid URL for the callback.
29	Description Non-Whitelisted Destination. Your Vonage account is still in demo mode. While in demo mode you must add target numbers to your whitelisted destination list. Résolution Top-up your account to remove this limitation.
32	Description Signature And API Secret Disallowed. A signed request may not also present an `api_secret`. Résolution Remove the API secret from your request, or don't sign the message.
33	Description Number De-activated. The number you are trying to send messages to is de-activated and may not receive them. Résolution N/A

SMS API

Opérations disponibles

Send an SMS

Authentification

Trajectoire Paramètres

Corps de la demande Type de contenuapplication/x-www-form-urlencoded

Exemple Demande

Réponses Type de contenuapplication/json

Exemple Réponse»Message sent

Delivery Receipt callback

Corps de la demande Type de contenuapplication/json

Exemple Charge utile

Réponses

Crochets Web

Opérations disponibles

Inbound SMS webhook

Corps de la demande Type de contenuapplication/json

Exemple Charge utile

Réponses

Erreurs

Corps de la demande
Type de contenu
application/x-www-form-urlencoded

Réponses
Type de contenu
application/json

Corps de la demande
Type de contenu
application/json

Corps de la demande
Type de contenu
application/json