Messages API

Versión 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.

Descargar la especificación OpenAPI

Operaciones disponibles

Send a Message

Send a Message

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

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

Autenticación

Esta API admite tanto la autenticación JWT como la básica. La autenticación básica es más fácil para empezar, pero no admite funciones avanzadas como ACL.

Puede utilizar o bien la autenticación JWT o Basic, pero no ambas a la vez.

Clave	Descripción	Dónde	Ejemplo
Authorization	Su token web JSON. Más información sobre los JWT	Headers	`Bearer <JWT>`
Authorization	Clave API codificada en Base64 y secreto unidos por dos puntos. Seguir leyendo	Headers	`Basic <base64>`

Cuerpo de la solicitud
Tipo de contenido
application/json

Uno de

client_ref

string

ejemploclient-ref2

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

object

Requerido

type

string

Requerido

ejemplosms

The channel the message is going to.

Debe ser uno de:sms

number

string

Requerido

ejemplo447700900000

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

Requerido

type

string

Requerido

ejemplosms

The channel the message is coming from

Debe ser uno de:sms

number

string

Requerido

ejemplo447700900001

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

Requerido

content

object

Requerido

type

string

Requerido

ejemplotext

The content type of the message

Debe ser uno de:text

text

string

Requerido

ejemploHello 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.

Ejemplo Solicitar

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

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

Respuestas
Tipo de contenido
application/json

Accepted.

message_uuid

string

Requerido

ejemploaaaaaaaa-bbbb-cccc-dddd-0123456789ab

The UUID of the message.

Ejemplo Respuesta

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

Cuerpo de la solicitud
Tipo de contenido
application/json

message_uuid

string

Requerido

ejemploaaaaaaaa-bbbb-cccc-dddd-0123456789ab

The UUID of the message.

object

Requerido

type

string

Requerido

ejemplosms

The type of message that you want to send.

Debe ser uno de:smsviber_service_msgmessengerwhatsappmms

string

Min1

Max50

ejemplo0123456789012345

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

number

string

Min1

Max50

ejemplo447700900000

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

Requerido

type

string

Requerido

ejemplosms

The type of message that you want to send.

Debe ser uno de:smsviber_service_msgmessengerwhatsappmms

string

Min1

Max50

ejemplo0123456789012345

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

Min1

Max50

ejemplo447700900000

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)

Requerido

ejemplo2020-01-01T14:00:00.000Z

The datetime of when the event occurred.

status

string

Requerido

ejemplodelivered

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

Debe ser uno de:submitteddeliveredreadrejectedundeliverable

error

object

code

integer

ejemplo1300

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

reason

string

ejemploNot part of the provider network

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

usage

object

currency

string

ejemploEUR

The charge currency in ISO 4217 format.

Debe ser uno de:EUR

price

string

ejemplo0.0333

The charge amount as a stringified number.

client_ref

string

ejemplomy-personal-reference

The client's reference.

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

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 Message

Inbound Message webhook

An inbound message from a customer to you.

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

Cuerpo de la solicitud
Tipo de contenido
application/json

Uno de

message_uuid

string

Requerido

ejemploaaaaaaaa-bbbb-cccc-dddd-0123456789ab

The UUID of the message.

timestamp

string(ISO 8601)

Requerido

ejemplo2020-01-01T14:00:00.000Z

The datetime of when the event occurred.

object

Requerido

type

string

Requerido

ejemplosms

The channel the message is going to.

Debe ser uno de:sms

number

string

Requerido

ejemplo447700900000

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

from

object

Requerido

type

string

Requerido

ejemplosms

The channel the message is coming from

Debe ser uno de:sms

number

string

Requerido

ejemplo447700900001

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

message

object

Requerido

content

object

Requerido

type

string

Requerido

ejemplotext

The content type of the message

Debe ser uno de:text

text

string

Requerido

ejemploHello From Vonage!

The UTF-8 encoded text of the inbound message.

sms

object

Requerido

num_messages

string

Requerido

ejemplo2

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

Requerido

currency

string

Requerido

ejemploEUR

The charge currency in ISO 4217 format.

Debe ser uno de:EUR

price

string

Requerido

ejemplo0.0333

The charge amount as a stringified number.

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

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ódigo	Información
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.

Messages API

Operaciones disponibles

Send a Message

Autenticación

Cuerpo de la solicitud Tipo de contenidoapplication/json

Ejemplo Solicitar

Respuestas Tipo de contenidoapplication/json

Ejemplo Respuesta

Message Status callback

Cuerpo de la solicitud Tipo de contenidoapplication/json

Ejemplo Carga útil

Respuestas

Webhooks

Operaciones disponibles

Inbound Message webhook

Cuerpo de la solicitud Tipo de contenidoapplication/json

Ejemplo Carga útil

Respuestas

Errores

Cuerpo de la solicitud
Tipo de contenido
application/json

Respuestas
Tipo de contenido
application/json

Cuerpo de la solicitud
Tipo de contenido
application/json

Cuerpo de la solicitud
Tipo de contenido
application/json