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

Descargar la especificación OpenAPI
Operaciones disponibles

Send an SMS

Send an outbound SMS from your Vonage account

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

Autenticación

ClaveDescripciónDóndeEjemplo
Authorization

Clave API codificada en Base64 y secreto unidos por dos puntos.
Seguir leyendo

Headers

Basic <base64>

Ruta Parámetros

format
string
Requerido
Por defectojson
ejemplojson

The format of the response

Debe ser uno de:jsonxml

Cuerpo de la solicitud
Tipo de contenido
application/x-www-form-urlencoded

api_key
string
Min8
Max8
ejemploabcd1234

Your API key. Only required if setting sig.

sig
string
Min16
Max60
ejemplo5d41402abc4b2a76b9719d911017c592

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
ejemplo1617187200

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
Requerido
ejemploAcmeInc

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
string
Requerido
Min7
Max15
ejemplo447700900000

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

text
string
Requerido
ejemploHello 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
Por defecto259200000
ejemplo900000

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
Por defectotrue

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

callback
string
ejemplohttps://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

Debe ser uno de:0123
type
string
Por defectotext
ejemplotext

Advanced: The format of the message body

Debe ser uno de:textbinaryunicode
body
string
ejemplo0011223344556677

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

udh
string
ejemplo06050415811581

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

protocol-id
integer
ejemplo127

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

client-ref
string
ejemplomy-personal-reference

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

account-ref
string
ejemplocustomer1234

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
ejemplo1101456324675322134

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
ejemplo1107457532145798767

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
ejemplotrue

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
ejemploabc123

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.

Ejemplo Solicitar

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

Respuestas
Tipo de contenido

Success

Uno de
message-count
string
ejemplo1

The amount of messages in the request

messages
array
to
string
ejemplo447700900000

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

message-id
string
ejemploaaaaaaaa-bbbb-cccc-dddd-0123456789ab

The ID of the message

status
string
ejemplo0

The status of the message. See Troubleshooting Failed SMS.

remaining-balance
string
ejemplo3.14159265

Your estimated remaining balance

message-price
string
ejemplo0.03330000

The estimated cost of the message

network
string
ejemplo12345

The estimated ID of the network of the recipient

client-ref
string
ejemplomy-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
ejemplocustomer1234

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

Ejemplo Respuesta»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

Cuerpo de la solicitud
Tipo de contenido
application/json

msisdn
string
ejemplo447700900000

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

to
string
ejemploAcmeInc

The SenderID you set in from in your request.

network-code
string
ejemplo12345

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

messageId
string
ejemplo0A0000001234567B

The Vonage ID for this message.

price
string
ejemplo0.03330000

The cost of the message

status
string
ejemplodelivered

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

scts
string
ejemplo2001011400

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
ejemplo0

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
ejemploabcd1234

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

message-timestamp
string
ejemplo2020-01-01 12:00:00

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

Ejemplo Carga útil

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

Respuestas

Your server returns this code if it accepts the callback

Webhooks

Los webhooks son una extensión de una API, pero en lugar de que tu código solicite datos, la API te los envía a ti. Los datos llegan en una petición web a tu aplicación.

Para obtener más información sobre los webhooks, consulte nuestra página documentación sobre webhooks.

Esta API puede enviar cualquiera de los webhooks documentados a continuación a la URL que haya configurado. Debe responder con una respuesta HTTP 200 o 204, o se volverán a intentar las solicitudes.

Operaciones disponibles

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

Cuerpo de la solicitud
Tipo de contenido
application/json

api-key
string
Requerido
ejemploabcd1234

The Vonage API Key of the receiving account.

msisdn
string
Requerido
ejemplo447700900001

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

to
string
Requerido
ejemplo447700900000

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

messageId
string
Requerido
ejemploaaaaaaaa-bbbb-cccc-dddd-0123456789ab

The ID of the message

text
string
Requerido
ejemploHello world

The message body for this inbound message.

type
string
Requerido
ejemplotext

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
Requerido
ejemploHELLO

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

message-timestamp
string
Requerido
ejemplo{}

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

timestamp
string
ejemplo1578787200

A unix timestamp representation of message-timestamp.

nonce
string
ejemploaaaaaaaa-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
ejemplotrue

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

concat-ref
string
ejemplo1

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

concat-total
string
ejemplo3

The number of parts in this concatenated message.

concat-part
string
ejemplo2

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

Ejemplo Carga útil

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

Respuestas

Your server returns this code if it accepts the callback

Errores

La siguiente es una lista no exhaustiva de códigos de error que pueden producirse al utilizar esta API.

Estos códigos se suman a cualquiera de nuestros códigos de error genéricos.

CódigoInformación
1

Descripción

Throttled. You are sending SMS faster than the account limit.

Resolución

Refer to What is the Throughput Limit for Outbound SMS? for more information.

2

Descripción

Missing Parameters. Your request is missing one of the required parameters from, to, api_key, api_secret or text.

Resolución

Check your parameters and try again.

3

Descripción

Invalid Parameters. The value of one or more parameters is invalid.

Resolución

Check your parameters and try again.

4

Descripción

Invalid Credentials. Your API key and/or secret are incorrect, invalid or disabled.

Resolución

Visit the Dashboard and check your credentials.

5

Descripción

Internal Error. An error has occurred in the platform whilst processing this message.

Resolución

If the error persists, contact support.

6

Descripción

Invalid Message. The platform was unable to process this message, for example, an un-recognized number prefix.

Resolución

N/A

7

Descripción

Number Barred. The number you are trying to send messages to is blacklisted and may not receive them.

Resolución

N/A

8

Descripción

Partner Account Barred. Your Vonage account has been suspended.

Resolución

Contact support.

9

Descripción

Partner Quota Violation. You do not have sufficient credit to send the message.

Resolución

Top-up and retry.

10

Descripción

Too Many Existing Binds. The number of simultaneous connections to the platform exceeds your account allocation.

Resolución

Back-off and retry.

11

Descripción

Account Not Enabled For HTTP. This account is not provisioned for the SMS API.

Resolución

This error usually indicates that you should use SMPP instead.

12

Descripción

Message Too Long. The message length exceeds the maximum allowed.

Resolución

Send shorter messages.

14

Descripción

Invalid Signature. The signature supplied could not be verified.

Resolución

Check the documentation for signing messages or use one of the SDKs to handle the signing.

15

Descripción

Invalid Sender Address. You are using a non-authorized sender ID in the from field.

Resolución

This is most commonly seen in North America, where a Vonage long virtual number or short code is required.

17

Descripción

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.

Resolución

N/A

22

Descripción

Invalid Network Code. The network code supplied was either not recognized, or does not match the country of the destination address.

Resolución

Check the network code or remove it from your request.

23

Descripción

Invalid Callback Url. The callback URL supplied was either too long or contained illegal characters.

Resolución

Supply a valid URL for the callback.

29

Descripción

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.

Resolución

Top-up your account to remove this limitation.

32

Descripción

Signature And API Secret Disallowed. A signed request may not also present an api_secret.

Resolución

Remove the API secret from your request, or don't sign the message.

33

Descripción

Number De-activated. The number you are trying to send messages to is de-activated and may not receive them.

Resolución

N/A