Messages API

Versão 0

The Messages API enables you to send messages to customers via their preferred channels (currently Facebook Messenger, WhatsApp, Viber, and SMS/MMS) using a single API. The Messages API is currently in Beta.

Baixar a especificação OpenAPI
Operações disponíveis

Send a Message

Send a Message over SMS, WhatsApp, Viber, Facebook Messenger, or MMS

posthttps://api.nexmo.com/v0.1/messages/

Autenticação

Esta API oferece suporte tanto à autenticação JWT quanto à autenticação básica. A autenticação básica é mais fácil de começar a usar, mas não oferece suporte a recursos avançados, como ACLs.

Você pode usar ou a autenticação JWT ou a autenticação básica, mas não ambas ao mesmo tempo.

ChaveDescriçãoOndeExemplo
Authorization

Seu token JSON da Web.
Saiba mais sobre os JWTs

Headers

Bearer <JWT>
Authorization

Chave e segredo da API codificados em Base64, separados por dois pontos.
Leia mais

Headers

Basic <base64>

Corpo da solicitação
Tipo de conteúdo
application/json

Um dos
client_ref
string
exemploclient-ref2

client reference up to 40 characters, the reference will be present in every message status

to
object
Obrigatório
type
string
Obrigatório
exemplosms

The channel the message is going to.

Deve ser uma das seguintes opções:sms
number
string
Obrigatório
exemplo447700900000

The phone number of the message recipient in the E.164 format. Don't use a leading + or 00 when entering a phone number, start with the country code, for example, 447700900000.

from
object
Obrigatório
type
string
Obrigatório
exemplosms

The channel the message is coming from

Deve ser uma das seguintes opções:sms
number
string
Obrigatório
exemplo447700900001

The Vonage Virtual number the message is originating from in the E.164 format. Don't use a leading + or 00 when entering a phone number, start with the country code, for example, 447700900000.

message
object
Obrigatório
content
object
Obrigatório
type
string
Obrigatório
exemplotext

The content type of the message

Deve ser uma das seguintes opções:text
text
string
Obrigatório
exemploHello From Vonage!

Limited to 1000 characters. The Messages API automatically detects unicode characters when sending SMS and sends the message as a unicode SMS. For more information on how concatenation and encoding please visit: developer.vonage.com/messaging/sms/guides/concatenation-and-encoding.

Exemplo Solicitação

{
   "client_ref": "client-ref2",
   "to": {
      "type": "sms",
      "number": "447700900000"
   },
   "from": {
      "type": "sms",
      "number": "447700900001"
   },
   "message": {
      "content": {
         "type": "text",
         "text": "Hello From Vonage!"
      }
   }
}
{
   "to": {
      "type": "sms",
      "number": "447700900000"
   },
   "from": {
      "type": "sms",
      "number": "447700900001"
   },
   "message": {
      "content": {
         "type": "text",
         "text": "Hello From Vonage!"
      }
   }
}

Respostas
Tipo de conteúdo
application/json

Accepted.

message_uuid
string
Obrigatório
exemploaaaaaaaa-bbbb-cccc-dddd-0123456789ab

The UUID of the message.

Exemplo Resposta

{
   "message_uuid": "aaaaaaaa-bbbb-cccc-dddd-0123456789ab"
}

Message Status callback

Webhooks to inform about events happening to the message at communication level (has it been delivered, rejected by the provider...).

posthttps://example.com/webhooks/message-status

Corpo da solicitação
Tipo de conteúdo
application/json

message_uuid
string
Obrigatório
exemploaaaaaaaa-bbbb-cccc-dddd-0123456789ab

The UUID of the message.

to
object
Obrigatório
type
string
Obrigatório
exemplosms

The type of message that you want to send.

Deve ser uma das seguintes opções:smsviber_service_msgmessengerwhatsappmms
id
string
Mín.1
Max50
exemplo0123456789012345

Messenger: The ID of the message recipient. This value should be the from.id value you received in the inbound messenger event.

number
string
Mín.1
Max50
exemplo447700900000

SMS, Viber, WhatsApp or MMS: The phone number of the message recipient in the E.164 format. Don't use a leading + or 00 when entering a phone number, start with the country code, for example, 447700900000.

from
object
Obrigatório
type
string
Obrigatório
exemplosms

The type of message that you want to send.

Deve ser uma das seguintes opções:smsviber_service_msgmessengerwhatsappmms
id
string
Mín.1
Max50
exemplo0123456789012345

Your ID for the platform that you are sending from.

Messenger: This value should be the to.id value you received in the inbound messenger event.

Viber: This is your Service Message ID given to you by your Vonage Account Manager. To find out more please visit vonage.com.

number
string
Mín.1
Max50
exemplo447700900000

SMS: The phone number of the message recipient in the E.164 format. Don't use a leading + or 00 when entering a phone number, start with the country code, for example, 447700900000.

WhatsApp: This is your WhatsApp Business Number given to you by your Vonage Account Manager. To find out more please visit vonage.com.

MMS: US shortcode

timestamp
string(ISO 8601)
Obrigatório
exemplo2020-01-01T14:00:00.000Z

The datetime of when the event occurred.

status
string
Obrigatório
exemplodelivered

The status of the message. The read message status is available for messenger, whatsapp and viber.

Deve ser uma das seguintes opções:submitteddeliveredreadrejectedundeliverable
error
object
code
integer
exemplo1300

The error code. See our errors list for a list of possible errors

reason
string
exemploNot part of the provider network

Text describing the error. See our errors list for a list of possible errors

usage
object
currency
string
exemploEUR

The charge currency in ISO 4217 format.

Deve ser uma das seguintes opções:EUR
price
string
exemplo0.0333

The charge amount as a stringified number.

client_ref
string
exemplomy-personal-reference

The client's reference.

Exemplo Carga útil

{
   "message_uuid": "aaaaaaaa-bbbb-cccc-dddd-0123456789ab",
   "to": {
      "type": "sms",
      "id": "0123456789012345",
      "number": "447700900000"
   },
   "from": {
      "type": "sms",
      "id": "0123456789012345",
      "number": "447700900000"
   },
   "timestamp": "2020-01-01T14:00:00.000Z",
   "status": "delivered",
   "error": {
      "code": 1300,
      "reason": "Not part of the provider network"
   },
   "usage": {
      "currency": "EUR",
      "price": "0.0333"
   },
   "client_ref": "my-personal-reference"
}

Respostas

Your server returns this code if it accepts the callback.

Webhooks

Os webhooks são uma extensão de uma API, mas, em vez de seu código solicitar dados, é a API que envia os dados para você. Os dados chegam por meio de uma solicitação da web ao seu aplicativo.

Para saber mais sobre webhooks, consulte nosso artigo “ documentação sobre webhooks ”.

Esta API pode enviar qualquer um dos webhooks documentados abaixo para a URL que você configurou. Você deve responder com uma resposta HTTP do tipo “ 200 ” ou “ 204 ”; caso contrário, as solicitações serão repetidas.

Operações disponíveis

Inbound Message webhook

An inbound message from a customer to you.

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

Corpo da solicitação
Tipo de conteúdo
application/json

Um dos
message_uuid
string
Obrigatório
exemploaaaaaaaa-bbbb-cccc-dddd-0123456789ab

The UUID of the message.

timestamp
string(ISO 8601)
Obrigatório
exemplo2020-01-01T14:00:00.000Z

The datetime of when the event occurred.

to
object
Obrigatório
type
string
Obrigatório
exemplosms

The channel the message is going to.

Deve ser uma das seguintes opções:sms
number
string
Obrigatório
exemplo447700900000

The Vonage Virtual number the sms is being sent to in the E.164 format.

from
object
Obrigatório
type
string
Obrigatório
exemplosms

The channel the message is coming from

Deve ser uma das seguintes opções:sms
number
string
Obrigatório
exemplo447700900001

The phone number the message is originating from in the E.164 format.

message
object
Obrigatório
content
object
Obrigatório
type
string
Obrigatório
exemplotext

The content type of the message

Deve ser uma das seguintes opções:text
text
string
Obrigatório
exemploHello From Vonage!

The UTF-8 encoded text of the inbound message.

sms
object
Obrigatório
num_messages
string
Obrigatório
exemplo2

The number of inbound SMS messages concatenated together to comprise this message. SMS messages are 160 characters, if an inbound message exceeds that size they are concatenated together to forma single message. This number indicates how many messages formed this webhook.

usage
object
Obrigatório
currency
string
Obrigatório
exemploEUR

The charge currency in ISO 4217 format.

Deve ser uma das seguintes opções:EUR
price
string
Obrigatório
exemplo0.0333

The charge amount as a stringified number.

Exemplo Carga útil

{
   "message_uuid": "aaaaaaaa-bbbb-cccc-dddd-0123456789ab",
   "timestamp": "2020-01-01T14:00:00.000Z",
   "to": {
      "type": "sms",
      "number": "447700900000"
   },
   "from": {
      "type": "sms",
      "number": "447700900001"
   },
   "message": {
      "content": {
         "type": "text",
         "text": "Hello From Vonage!"
      },
      "sms": {
         "num_messages": "2"
      }
   },
   "usage": {
      "currency": "EUR",
      "price": "0.0333"
   }
}

Respostas

Your server returns this code if it accepts the callback.

Erros

A seguir, apresentamos uma lista não exaustiva de códigos de erro que podem ocorrer durante o uso desta API.

Esses códigos são adicionais aos que constam em nosso site códigos de erro genéricos.

CódigoInformações
1000

Throttled - You have exceeded the submission capacity allowed on this account. Please wait and retry

1010

Missing params - Your request is incomplete and missing some mandatory parameters.

1020

Invalid params - The value of one or more parameters is invalid.

1021

Invalid tag - The tag value is invalid.

1022

Invalid template - Invalid template or template parameters

1030

Internal error - There was an error processing your request in the Platform.

1040

Invalid message - The Platform was unable to process your request. For example, due to an unrecognised prefix for the phone number.

1050

Number barred - The number you are trying to submit to is blacklisted and may not receive messages.

1060

Partner account barred - The api_key you supplied is for an account that has been barred from submitting messages.

1070

Partner quota exceeded - Your pre-paid account does not have sufficient credit to process this message.

1080

Account not enabled for REST - This account is not provisioned for REST submission, you should use SMPP on the SMS API.

1090

Message too long - The length of udh and body was greater than 140 octets for a binary type SMS request.

1100

Communication Failed - Message was not submitted because there was a communication failure.

1120

Illegal Sender Address - rejected - Due to local regulations, the SenderID you set in from in the request was not accepted. Please check the Global messaging section.

1130

Invalid TTL - The value of ttl in your request was invalid.

1140

Facility not allowed - Your request makes use of a facility that is not enabled on your account.

1150

Invalid Message class - The value of message-class in your request was out of range. See https://en.wikipedia.org/wiki/Data_Coding_Scheme.

1160

Non White-listed Destination - The phone number you set in to is not in your pre-approved destination list. To send messages to this phone number, add it using Dashboard.

1170

Invalid or Missing Msisdn Param - The phone number you supplied in the to parameter of your request was either missing or invalid.

1180

Absent Subscriber Temporary - This message was not delivered because to was temporarily unavailable. For example, the handset used for to was out of coverage or switched off. This is a temporary failure, retry later for a positive result.

1190

Absent Subscriber Permanent - to is no longer active, You should remove this phone number from your database.

1200

Portability Error - There is an issue after the user has changed carrier for to. If the user wants to receive messages from you, they need to contact their carrier directly.

1210

Anti-Spam Rejection - Carriers often apply restrictions that block messages following different criteria. For example on SenderID or message content.

1220

Handset Busy - The handset associated with to was not available when this message was sent. If status is rejected, this is a temporary failure; retry later for a positive result. If status is submitted, this message has is in the retry scheme and will be resent until it expires in 24-48 hours.

1230

Network Error - A network failure while sending your message. This is a temporary failure, retry later for a positive result.

1240

Illegal Number - You tried to send a message to a blacklisted phone number. That is, the user has already sent a STOP opt-out message and no longer wishes to receive messages from you.

1241

Too many send requests - Too many send requests to phone numbers.

1250

Unroutable - The chosen route to send your message is not available. This is because the phone number is either currently on an unsupported network or on a pre-paid or reseller account that could not receive a message sent by from. To resolve this issue either email support or create a helpdesk ticket here.

1260

Destination unreachable - The message could not be delivered to the phone number. If using Viber Business Messages your account might not be enabled for this country.

1270

Subscriber Age Restriction - The carrier blocked this message because the content is not suitable for to based on age restrictions.

1280

Number Blocked by Carrier - The carrier blocked this message. This could be due to several reasons. For example, to's plan does not include SMS or the account is suspended.

1290

Pre-Paid - Insufficient funds - to’s pre-paid account does not have enough credit to receive the message.

1300

Not part of the provider network - The number or ID is not a user in the provider network.

1310

Not suitable device - The user's device can't receive the message.

1320

Message already sent - The message was already sent.

1330

Unknown - An unknown error was received from the carrier who tried to send this this message. Depending on the carrier, that to is unknown. When you see this error, and status is rejected, always check if to in your request was valid.

1331

Provider error - The provider is not responding or unable to process the request. Please try sending your message in a few minutes time.

1340

Outside of the allowed window - This message is sent outside of allowed response window.

1350

Phone matching fee not paid - Requires phone matching access fee to be paid by the Facebook Page.

1360

TTL was activated - TTL was activated, no callbacks and no charge will be issued.

1370

Expired access Token - Please reauthenticate your Facebook Page with Vonage.

1380

Invalid resource - Please check that the URL your provided to your resrouce is accesible and valid.

1381

Resource size is too large - Please try sending a smaller media file.

1382

Resource type is invalid - Please check that the file you are trying to send is valid.