WhatsApp API

Documentación técnica: WhatsApp API.

API de WhatsApp

Esta documentación proporciona información sobre cómo su aplicación puede enviar mensajes de Whatsapp a través de la API utilizando la plataforma Sinch Messaging.

También encontrará información aquí sobre Webhooks, que son devoluciones de llamada HTTP definidas por el usuario que se desencadenan por eventos específicos. Cada vez que ocurra un evento desencadenante, la API de Sinch recopilará los datos e inmediatamente enviará una notificación (solicitud HTTP) a la URL elegida por el cliente, actualizando el estado de los mensajes enviados o indicando cuándo recibe un mensaje.

La API Sinch Messaging permite enviar mensajes individuales o por lotes.

La API tiene integración REST, utilizando el protocolo HTTP con TLS, soportando el método POST con los parámetros enviados en formato JSON.

Requisitos previos

  1. Para utilizar la API de mensajería de Sinch, primero debe tener una cuenta activa en la plataforma de mensajería de Sinch.

  2. También debe tener un nombre de usuario y un token válidos asociados con esta cuenta.

  3. Aprenda cómo crear su usuario en nuestra guía Agregar usuarios. Con las credenciales anteriores, puede comenzar a usar Sinch Messaging API.

Detalhes da conexão

CampoDescripción

Hostname

api-messaging.wavy.global

Porta

443 (https)

Protocolo

HTTPS (TLS encryption)

Autenticação

username + token

Encoding

UTF-8

Realización de llamadas a la API Sinch Messaging

Para realizar tus primeras llamadas te recomendamos utilizar la aplicación “Cartero” con solicitudes en formato JSON en lugar de empezar a escribir códigos en otros lenguajes.

Nota: Para enviar mensajes de prueba, debe tener una plantilla de mensaje aprobada en su cuenta de WhatsApp Business. Consulte nuestra documentación de creación de plantillas de mensajes de WhatsApp para crear sus primeras plantillas.

Si aún no tiene ningún modelo de mensaje aprobado, aún puede enviar mensajes de prueba, siempre que el destinatario interactúe con el número de origen.

De esta forma, se activará una ventanilla de atención al cliente. Le permite enviar cualquier tipo de mensaje dentro de una ventana de 24 horas. Si el mensaje llega, su solicitud a Sinch Messaging API fue exitosa. De lo contrario, revise su Webhook para ver si hay notificaciones que puedan indicar un problema.

Mensajes:

Las llamadas a la API Sinch Messaging se envían a: https://api-messaging.wavy.global/v1/whatsapp/send en formato POST independientemente del tipo de mensaje, pero el contenido del cuerpo del mensaje JSON varía para cada tipo de mensaje. Los campos de autenticación en el encabezado también seguirán el mismo formato independientemente del tipo de mensaje:

POST /v1/whatsapp/send HTTP/1.1 Host: api-messaging.wavy.global UserName: user_name AuthenticationToken: aaaaaa-bbbbbbbbbbbbbXXXXX12 Content-Type: application/json

Envío de plantilla

Destinations

NomeObligatorioDescripción

destinations

Si

Detalles sobre identificadores de envío y destino

message

Si

Detalles sobre el objeto MESSEGE que se enviará

Destination

NomeObligatorioDescripción

correlationId

No

Id definido por el cliente que será devuelto en el estado del mensaje (devolución de llamada). Puede utilizar esta identificación para realizar un seguimiento de los envíos de mensajes de forma personalizada.

destination

Sim

Número de teléfono que recibirá el mensaje (código de país (55 para Brasil) y código de área son obligatorios). Ejemplos: 5519900001111, +5519900001111, +55(19) 900001111.

Message

NomeObligatorioDescripción

TTL

No

Vida útil en días. Define el número máximo de días que se debe entregar el mensaje. Válido de 1 a 30. Valor por defecto 7 si no se define

Template

Sim

Detalles sobre el objeto TEMPLATE que se enviará

Template

NomeObligatorioDescripción

Namespace

Si

Id. del espacio de nombres que se utilizará. NOTA: Los parámetros namespace y element_name deben coincidir con el Business Manager al que está asociado el número de origen, o el mensaje no se podrá enviar

ElementName

Si

Nombre del modelo registrado y aprobado.

header

Sí, cuando la plantilla tiene un parámetro en el encabezado

Objetos de encabezado con sus parámetros

LanguageCode

Si

Nombre del modelo registrado y aprobado.

Header

NomeObligatorioDescripción

Title

Opcional

El título debe tener hasta 60 caracteres.

Element

Si

Opções:

text (padrão),

image,

audio,

document,

hsm,

video.

Element

NomeObligatorioDescripción

Url

Si

URL de medios. Úselo solo con URL HTTP/HTTPS.

Type

Si

Tipo de medio (JPEG, MP3, PDF, etc.)

Caption

Si

nombre de los medios

Webhooks

Los webhooks (o devoluciones de llamada) son devoluciones de llamada HTTP definidas por el usuario que se desencadenan por eventos específicos. Cada vez que ocurra un evento desencadenante, la API de Sinch recopilará los datos e inmediatamente enviará una notificación (solicitud HTTP) a la URL elegida por el cliente, actualizando el estado de los mensajes enviados o indicando cuándo recibe un mensaje.

Cuando el cliente le envía un mensaje, Sinch Messaging API enviará una notificación de solicitud HTTP POST a la URL del webhook con los detalles.

Es importante que su webhook devuelva una respuesta HTTPS 200 OK a las notificaciones (dentro de 200 ms o de forma asíncrona). De lo contrario, Sinch Messaging API considerará que esta notificación ha fallado y volverá a intentarlo después de un retraso.

Importante: Nuestro equipo de soporte debe configurar la URL donde recibirá los Webhooks.

Formato geral de um Webhook

Nome

Conteúdo do objeto

messages

Notificações de mensagens de entrada

statuses

Atualizações de status das mensagens

Estado

EstadoDescripciónEquivalente móvil de WhatsApp

SENT_SUCCESS

Mensaje recibido por el servidor de WhatsApp

una marca de verificación

DELIVERED_SUCCESS

Mensaje entregado al destinatario

dos marcas de verificación

READ_SUCCESS

Mensaje leído por el destinatario

Dos marcas de verificación azules

Erros

HTTP Code

Description

2xx

Success

200

Success (OK)

201

Successfully created (For POST requests)

302

Found

4xx

Client Errors

400

Request was invalid

401

Unauthorized

403

Forbidden

404

Not found

405

Method not allowed

412

Precondition failed

420

Message is rate limited

429

Too many requests

5xx

Server Errors

500

Internal server error

504

Timeout

Outros status

código de envíocódigo de entregaEstadoSignificado

102

CARRIER COMMUNICATION ERROR

Error al cargar medios a WhatsApp

103

REJECTED_BY_CARRIER

Ocurrió un error en la base de datos

2

101

EXPIRED

mensaje caducado

2

104

NOT_DELIVERED

Posibles Causas: Se ha alcanzado el límite: se han intentado demasiados envíos de mensajes. o no se pudo enviar el mensaje porque el número de teléfono objetivo es parte de un experimento, o la estructura de la plantilla no existe, o no se pudo enviar el mensaje porque el número de destino está fuera de la ventana de servicio de 24 horas para recibir mensajes de formato libre. o hubo un error de carga de medios (error desconocido), o no pudo enviar el mensaje porque su cuenta no es elegible en Facebook Business Manager, o hubo un error de carga temporal. Vuelva a intentarlo más tarde.

202

INVALID_DESTINATION_NUMBER

Contacto de WhatsApp inválido

204

DESTINATION_BLOCKED_BY_OPTOUT

Destino bloqueado por exclusión voluntaria

206

INVALID_MESSAGE_LENGTH

mensaje demasiado largo

207

INVALID_MESSAGE_TEXT

El valor del parámetro no es válido

209

INVALID_CONTENT

Tipo de mensaje DESCONOCIDO no válido

210

INVALID_SESSION

La ventana de sesión o de escucha no está abierta y no se ha configurado ninguna plantilla alternativa

311

INTERNAL_ERROR

No se pueden verificar los contactos de la API de WhatsApp

Mensajes (MO)

Cuando el cliente le envía un mensaje, Sinch Messaging API enviará una notificación de solicitud HTTP POST a la URL del webhook con los detalles.

Cuando el cliente le envía un mensaje, Sinch Messaging API enviará una notificación de solicitud HTTP POST a la URL del webhook con los detalles. Es importante que su webhook devuelva una respuesta HTTPS 200 OK a las notificaciones (dentro de 200 ms o de forma asíncrona). De lo contrario, Sinch Messaging API considerará que esta notificación ha fallado y volverá a intentarlo después de un retraso.

Importante: Nuestro equipo de soporte debe configurar la URL donde recibirá los Webhooks.

Respuesta de código de estado HTTP común

Solicitud de respuesta exitosa (200)

Si la solicitud se ejecuta con éxito, se devolverá la lista de destinos con los uuid generados:

{
 "Id": "5efc3581-b8e8-11e7-9895-a6aabe61edb5",
  "destination": [{
  "id": "5efc3581-b8e8-11e7-9895-a6aabe61edb5",
  "correlationId": "MyCorrelationId",
  "destination": "5519900001111."
}]
}

Respuesta de error de autenticación (401)

Si hay un problema con la autenticación, se devolverá el siguiente mensaje:

{
  "errorCode": 401,
  "errorMessage": "Autenticação Error: No user was found with this combination of username and Autenticação token."
}

Actualización de estado de devolución de llamada

Ejemplo

{
  "total": 1,
  "data": [
    {
      "id": "8995c40f-1c3a-48d0-98ee-bbc603622a91",
      "correlationId": "...",
      "destination": "5519900000000",
      "origin": "5519900000000",
      "campaignId": 100,
      "campaignAlias": "...",
      "flowId": "...",
      "extraInfo": "...",
      "sent": true,
      "sentStatusCode": 1,
      "sentStatus": "sent status",
      "sentDate": "2017-12-18T17:09:31.891Z",
      "sentAt": 1513616971891,
      "delivered": true,
      "deliveredStatusCode": 1,
      "deliveredStatus": "delivered status",
      "deliveredDate": "2017-12-18T17:09:31.891Z",
      "deliveredAt": 1513616971891,
      "read": true,
      "readDate": "2017-12-18T17:09:31.891Z",
      "readAt": 1513616971891,
      "updatedDate": "2017-12-18T17:09:31.891Z",
      "updatedAt": 1513616971891
    }
  ],
  "clientInfo": {
      "customerId": 42,
      "subAccountId": 1291,
      "userId": 1
  }
}

Cada actualización del estado de los mensajes enviados (confirmación de entrega al usuario final, lectura de mensajes, etc.), se envía una devolución de llamada/webhook. Las devoluciones de llamada se envían por lotes.

Importante: Nuestro equipo de soporte y operaciones debe configurar el punto final que usará el webhook para enviar los estados.

El formato de devolución seguirá la siguiente descripción:

CampoDetallesTipo

total

Número de devoluciones de llamada en la llamada.

String

data

Lista de devolución de llamada.

Data[]

clientInfo

Información al cliente.

ClientInfo

Dados:

CampoDetallesTipo

id

identificación del último mensaje

String

correlationId

Una ID única definida por usted para que coincida con el estado del mensaje (Devolución de llamada y DLR). Este parámetro es opcional y puede utilizar el ID generado por Sinch Messaging para realizar la comparación.

String

destination

Número de teléfono al que se envió el mensaje (incluido el código de país). Ejemplo: 5511900000000.

String

origin

Número de telefone que Número de teléfono al que se envió el mensaje (incluido el código de país). Ejemplo: 5511900000000.

String

campaignId

ID de campaña definido anteriormente.

String

campaignAlias

Alias ​​de campaña definido anteriormente.

String

extraInfo

Información adicional enviada con el mensaje original.

String

sent

Indica si el mensaje fue enviado.

Boolean

sentStatusCode

Código de estado generado por Sinch Messaging para el mensaje que indica el estado de envío.

Number

sentStatus

Descripción del estado del envío.

Boolean

sentDate

Fecha en que se envió el mensaje. formato: aaaa-MM-dd'T'HH:mm:ssZ.

String

sentAt

Hora en que se envió el mensaje, utilizando el formato de hora Unix

Number

delivered

Indica si el mensaje se entregó en el destino.

Boolean

deliveredStatusCode

Código de estado generado por Sinch Messaging que indica si el mensaje fue entregado.

Number

deliveredStatus

Descripción del estado de entrega.

String

deliveredDate

Fecha en que se entregó el mensaje. formato:: aaaa-MM-dd'T'HH:mm:ssZ

String

deliveredAt

Tempo em que a mensagem foi entregue, usando Unix_time format

Number

read

Indica si el destinatario ha leído el mensaje.

Boolean

readDate

Fecha en que se leyó el mensaje. formato: aaaa-MM-dd'T'HH:mm:ssZ

String

readAt

Hora en que se leyó el mensaje, utilizando el formato Unix Time

String

updatedDate

Fecha en que se actualizó el estado del mensaje. Formato: aaaa-MM-dd'T'HH:mm:ssZ

String

updatedAt

Fecha en que se actualizó el estado del mensaje, utilizando el formato Unix_time

String

ClientInfo

CampoDetalhesTipo

customerId

Identificación del cliente.

Number

subAccountId

ID de subcuenta.

Number

userId

Identificación de usuario.

Number

Status

Status que podem ser enviados no callback:

StatusCódigo de envioCódigo de entregaSignificado

CARRIER_COMMUNICATION_ERROR

102

Error al cargar medios a WhatsApp.

REJECTED_BY_CARRIER

103

Ocurrió un error en la base de datos.

SENT_SUCCESS

2

EXPIRED

2

101

Mensaje caducado.

No se pudo enviar el mensaje porque es demasiado antiguo.

NOT_DELIVERED

2

104

Se alcanzó el límite: se intentaron demasiados envíos de mensajes.

DELIVERED_SUCCESS

2

4

READ_SUCCESS

2

5

INVALID_DESTINATION_NUMBER

202

Contacto de WhatsApp no ​​válido.

DESTINATION_BLOCKED_BY_OPTOUT

204

Destino bloqueado por OptOut.

INVALID_MESSAGE_LENGTH

206

Mensaje demasiado largo.

INVALID_MESSAGE_TEXT

207

El valor del parámetro no es válido.

INVALID_CONTENT

209

Tipo de mensaje DESCONOCIDO no válido.

INVALID_SESSION

210

La sesión no está abierta y no se ha configurado ningún HSM de respaldo.

DESTINATION_BLOCKED_BY_OPTIN

211

DESTINATION_BLOCKED_BY_WHITELIST

212

INTERNAL_ERROR

311

No es posible verificar los contactos de la API de WhatsApp.

MO (mensajes enviados por el usuario final a la cuenta de Whatsapp)

Ejemplo de mensaje de texto:

{
  "total": 1,
  "data": [
    {
      "id": "ce425ffe-bc62-421f-9261-e6819a5eab43",
      "source": "5519900000000",
      "origin": "5519900000000",
      "userProfile": {
        "name": "nome do usuário"
      },
      "campaignId": 100,
      "correlationId": "...",
      "campaignAlias": "...",
      "flowId": "....",
      "extraInfo": "...",
      "message": {
            "type": "TEXT",
"messageText": "Olá, essa é uma mensagem do usuário."
      },
      "receivedAt": 1513616971473,
      "receivedDate": "2017-12-18T17:09:31.473Z"
    }
  ]
}

Ejemplo de información adicional:

{  
   "segmentation_list":[  
      {  
         "id":26,
         "customerId":42,
         "subAccountId":0,
         "name":"Sinch WhatsApp Segmentation List",
         "active":true
      },
      {  
         "id":27,
         "customerId":43,
         "subAccountId":0,
         "name":"Sinch WhatsApp Segmentation List 2",
         "active":true
      }
   ]
}

Ejemplo de mensaje multimedia

{
  "total": 1,
  "data": [
    {
      "id": "ce425ffe-bc62-421f-9261-e6819a5eab43",
      "source": "5519900000000",
      "origin": "5519900000000",
      "userProfile": {
        "name": "nome do usuário"
      },
      "campaignId": 100,
      "correlationId": "...",
      "campaignAlias": "...",
      "flowId": "....",
      "extraInfo": "...",
      "message": {
            "type": "IMAGE",
           "mediaUrl": "https://...",
           "mimeType": "image/jpg",
           "caption": "..."
      },
      "receivedAt": 1513616971473,
      "receivedDate": "2017-12-18T17:09:31.473Z"
    }
  ]
}

Ejemplo de mensaje de ubicación:

{
  "total": 1,
  "data": [
    {
      "id": "ce425ffe-bc62-421f-9261-e6819a5eab43",
      "source": "5519900000000",
      "origin": "5519900000000",
      "userProfile": {
        "name": "nome do usuário"
      },
      "campaignId": 100,
      "correlationId": "...",
      "campaignAlias": "...",
      "flowId": "....",
      "extraInfo": "...",
      "message": {
           "location": {
               "geoPoint": "-22.894180,-47.047960",
               "name": "Sinch",
               "address": "Av. Cel. Silva Telles"
           }
      },
      "receivedAt": 1513616971473,
      "receivedDate": "2017-12-18T17:09:31.473Z"
    }
  ]
}

Ejemplo de mensaje de contacto:

{
  "total": 1,
  "data": [
    {
      "id": "ce425ffe-bc62-421f-9261-e6819a5eab43",
      "source": "5519900000000",
      "origin": "5519900000000",      
      "userProfile": {
        "name": "nome do usuário"
      },
      "campaignId": 100,
      "correlationId": "...",
      "campaignAlias": "...",
      "flowId": "....",
      "extraInfo": "...",
      "message": {
           "contacts":[  
                 {  
                    "addresses":[  
                       {  
                          "city":"Menlo Park",
                          "country":"United States",
                          "country_code":"us",
                          "state":"CA",
                          "street":"1 Hacker Way",
                          "type":"HOME",
                          "zip":"94025"
                       },
                       {  
                          "city":"Menlo Park",
                          "country":"United States",
                          "country_code":"us",
                          "state":"CA",
                          "street":"200 Jefferson Dr",
                          "type":"WORK",
                          "zip":"94025"
                       }
                    ],
                    "birthday":"2012-08-18",
                    "emails":[  
                       {  
                          "email":"test@fb.com",
                          "type":"WORK"
                       },
                       {  
                          "email":"test@whatsapp.com",
                          "type":"WORK"
                       }
                    ],
                    "name":{  
                       "first_name":"John",
                       "formatted_name":"John Smith",
                       "last_name":"Smith"
                    },
                    "org":{  
                       "company":"WhatsApp",
                       "department":"Design",
                       "title":"Manager"
                    },
                    "phones":[  
                       {  
                          "phone":"+1 (940) 555-1234",
                          "type":"HOME"
                       },
                       {  
                          "phone":"+1 (650) 555-1234",
                          "type":"WORK",
                          "wa_id":"16505551234"
                       }
                    ],
                    "urls":[  
                       {  
                          "url":"https://www.fb.com",
                          "type":"WORK"
                       }
                    ]
                 }
              ]
      },
      "receivedAt": 1513616971473,
      "receivedDate": "2017-12-18T17:09:31.473Z"
    }
  ]
}

Cada respuesta del usuario final (MO o Mobile Origined) se envía una devolución de llamada/webhook. Estos MO se envían por lotes.

Importante: Nuestro equipo de soporte y operaciones debe configurar el punto final que usará el webhook para enviar los estados.

Importante: Nuestro equipo de soporte y operaciones debe configurar el punto final que usará el webhook para enviar los estados.

CampoDetallesTipo

total

Números de devolución de llamada para la llamada.

String

data

Lista de mensajes con origen móvil (MO).

Data[]

Dados

CampoDetallesTipo

id

Identificación del último mensaje

String

source

Número de teléfono del remitente

String

origin

Número de teléfono que identifica la Cuenta de WhatsApp (incluyendo código de país). Ejemplo: 5511900000000.

String

userProfile

Perfil del usuario que envió el mensaje

UserProfile

correlationId

Una ID única definida por usted para que coincida con el estado del mensaje (Devolución de llamada y DLR). Este parámetro es opcional y puede usar la ID generada por Sinch Messaging para hacer la comparación.

String

campaignId

ID de campaña definido anteriormente.

String

campaignAlias

Alias ​​de campaña definido anteriormente.

String

mensagem

Mensaje MO.

mensagem

receivedAt

Fecha en que se recibió el mensaje. Formato: aaaa-MM-dd'T'HH:mm:ssZ

String

receivedDate

Fecha en que se recibió el mensaje, utilizando el formato de hora Unix

String

extraInfo

Información adicional relacionada con el mensaje. Formato: JSON

String

Controle de Fluxo de MO- Listas de Segmentação

El mensaje tendrá una lista de listas de orientación en el campo extraInfo. Nuestros socios lo usan para dirigir mensajes a ciertos flujos. El nombre de la clave es segmentation_lists y contiene una lista de SegmentationList.

CampoDetallesTipo

id

Identificador de lista de segmentación

Integer

customerId

identificador de cliente

Integer

subAccountId

identificador de subcuenta

Integer

name

Nombre de la lista de objetivos

String

active

Estado de la lista de objetivos

Boolean

Mensaje:

CampoDetallesTipo

type

Tipo de mensaje enviado al usuario final: TEXTO - IMAGEN - AUDIO - DOCUMENTO

String

messageText

El mensaje de texto (MO) enviado por el usuario final.

String

waGroupId

Grupo al que se envió el mensaje.

String

mediaUrl

Url para descargar los medios enviados por el usuario final.

String

mimeType

Tipo Mime del archivo enviado por el usuario final.

String

caption

Etiqueta de medios enviada por el usuario final.

String

location

Ubicación enviada por el usuario final.

Location

contacts

Contactos enviados por el usuario final.

Contact[]

UserProfile:

CampoObligatorioDetallesTipo

name

Não

Nombre de perfil de usuario

String

Location:

CampoDetallesTipo

name

Nombre del lugar.

String

address

Dirección del sitio.

String

geoPoint

Geopunto enviado por el usuario final. Formato: "latitud, longitud"

String

Contact:

CampoObligatorioDetallesTipo

addresses

No

Dirección(es) completa(s) del contacto.

Address[]

birthday

No

Cumpleaños en formato AAAA-MM-DD.

String

emails

No

Dirección(es) de correo electrónico de contacto.

Email[]

name

No

Nombre completo del contacto.

Name

org

No

Información de contacto de la organización.

Org

phones

No

Teléfono(s) de contacto.

Phone[]

urls

No

URL de contacto.

Url[]

Address:

CampoObligatorioDetallesTipo

street

No

Nombre y número de la calle.

String

city

No

Nombre de la ciudad.

String

state

No

símbolo del estado.

String

zip

No

CÓDIGO POSTAL.

String

country

No

Nombre completo del país.

String

country_code

No

Abreviatura del país (Dos letras).

String

type

No

Valores por defecto: CASA, TRABAJO.

String

Email:

CampoObligatorioDetallesTipo

email

No

Dirección de correo electrónico.

String

type

No

Valores por defecto: CASA, TRABAJO.

String

Name:

CampoObligatorioDetallesTipo

first_name

No

Primer nombre.

String

last_name

No

Ultimo nombre.

String

middle_name

No

Nombre del medio.

String

name_suffix

No

Sufijo de nombre.

String

name_prefix

No

Prefijo del nombre.

String

formatted_name

No

Nombre completo como aparece normalmente.

String

Org:

CampoObligatorioDetallesTipo

company

No

Nombre de la organización del contacto.

String

department

No

Nombre del departamento del contacto.

String

title

No

Título corporativo del contacto.

String

Phone:

CampoObligatorioDetallesTipo

phone

No

Número de teléfono formateado.

String

type

No

Valores predeterminados: CELULAR, PRINCIPAL, IPHONE, CASA, TRABAJO.

String

wa_id

No

Identificador de WhatsApp.

String

Url:

CampoObligatorioDetallesTipo

phone

No

URL de contacto.

String

type

No

Valores por defecto: CASA, TRABAJO.

String

Para los objetos que contienen un campo de tipo, los valores enumerados simplemente se consideran los valores predeterminados que se pueden ver, sin embargo, puede establecer el campo en cualquier valor descriptivo que elija.

API SFTP WhatsApp

Detalles de conexión

CampoDescripción

Hostname

ftp-messaging.wavy.global

Porta

2222

Protocolo

SFTP (transferencia a través de ssh, que proporciona cifrado cliente-servidor)

Autenticação

nombre de usuario + contraseña (proporcionado por soporte)

Es necesario liberar tus IPs en los firewalls de Sinch. Si es necesario liberar el firewall para salida hacia el puerto 2222, debe liberar el DNS, o las IPs 200.219.220.54, 200.189.169.53 y 45.236.179.22

Envío de mensajes a través de SFTP

Para disparar mensajes a través de FTP, es necesario generar un archivo con formato siguiendo el ejemplo a continuación: Mensaje HSM:

2018-10-16;10:00;20:00;HSM;chatclub_welcome;pt_BR;DETERMINISTIC;nome|empresa telefone;nome;empresa 551999999999;Nome1;Sinch 551999999999;Nome2;Sinch

1ª Línea

Fecha de presentación (para casos de programación)

Hora de inicio de envío (para casos de programación)

Hora de envío final (para casos de programación)

El tipo de mensaje debe ser: HSM

Nombre (elementName) del HSM

Idioma (languageLocale) del HSM

Determinista o Fallback del lenguaje del HSM (languagePolicy)

Nombre de parámetros de HSM

Notas para la primera línea::

  1. Los nombres de los parámetros deben coincidir con los nombres de las columnas.

  2. La información que no se va a utilizar se puede dejar en blanco, pero el punto y coma se debe utilizar como separación. Ejemplo de un caso donde no usamos scheduling (los campos iniciales están entre punto y coma y sin información adentro): ; ; ; HSM;chatclub_welcome;en_BR;DETERMINISTIC;nombre|empresa

  3. De forma predeterminada (predeterminada), languagePolicy será determinista.

  4. Los nombres de los parámetros de HSM deben estar separados por “ | ” y no por “ ; ”

2ª Linha

nombres de columnas

3ª y otras lineas:

Valores de parámetros de destinatario y HSM

Consulta de lista a través de API

Pedido

Con GET, puede realizar una solicitud enviando todos los parámetros en la cadena de consulta

http://api-messaging.wavy.global/v1/list/{listType}?customerId={customerId}&subAccountId={subAccountId}

Tipo de ListaValor pasado en {listType}

Whatsapp OPT-OUT List

OPTOUT

Whatsapp OPT-IN List

OPTIN

Whatsapp Blacklist

BLACKLIST

Whatsapp Whitelist (para MT)

WHITELIST

El parámetro customerId es obligatorio, mientras que subAccountId es opcional.

Atención: las llaves '{' y '}' también deben reemplazarse.

Por ejemplo, "{listType}" se convierte en "OPTIN". Todavía es necesario pasar los siguientes encabezados:

HeaderValor

Content-Type

application/json

authenticationToken

Token do Messaging

userName

Nombre de usuario de mensajería

Respuesta

En caso de éxito, si hay datos asociados con customerId y subAccountId, la solicitud devolverá un JSON con 3 atributos:

AtributoValor

success

true

status

200

data

Enlace para descargar un archivo csv que contiene los campos "fuente" y "creado en" de todos los destinos encontrados

La columna "creado en" está en la zona horaria de América/Sao_Paulo, UTC-3 o UTC-2 en horario de verano.

Si no hay datos asociados, solo se devolverá un JSON similar, pero sin el campo de datos, lo que significa que no hubo problemas con la solicitud, pero no hubo datos relacionados con los parámetros pasados.

Ejemplo de respuesta:

{
    "success": true,
    "status": 200,
    "data": "https://chatclub-cdn.wavy.global/2019/02/12/f2b8effb-d0bc-4327-86c2-48fedcb01b1b/list-42-4330544192402746957.csv"
}

Consultar sesiones abiertas a través de API

Pedido

Para consultar las sesiones abiertas a través de nuestra API, debe realizar una solicitud GET a la dirección:

GET http://api-messaging.wavy.global/v1/session?customerId={customerId}&subAccountId={subAccountId}

El parámetro customerId es obligatorio, mientras que subAccountId es opcional.

Atención: Las llaves '{' y '}' también deben reemplazarse. Por ejemplo, “={customerId}” se convierte en “=42”.

Todavía es necesario pasar los siguientes encabezados

HeaderValor

Content-Type

application/json

authenticationToken

Token

userName

Nombre de usuario

El usuario y el token se pueden obtener a través de nuestra plataforma: Mi Perfil

Respuesta

En caso de éxito, si hay sesiones abiertas para el ID de cliente y el ID de subcuenta especificados, la solicitud devolverá un JSON con el atributo:

AtributoValor

file_url

Enlace para descargar un archivo csv que contiene los campos "fuente" y "session_created_at" de todos los destinos encontrados

Si no hay datos asociados con customerId y subAccountId, el archivo devuelto estará vacío, con solo el encabezado.

Ejemplo de respuesta:

{
    "file_url": "https://chatclub-cdn.wavy.global/2019/02/13/633e33fc-3a3f-4ca5-a8b0-4b747fb67137/5bd46e2b-5990-4681-9b29-98ab6598960e"
}

Destino:

CampoNecesarioDetallesTipo

correlationId

No

Su id definido sera devuelto en un mensaje de confirmación (Callback). Esto será útil en casos en que se desea mantener el control del mensaje enviado, ya que es posible definir ids diferentes para mensajes distintos.

String

destination

Si

Número de teléfono (código de país y estado deben estar presentes) o el WhatsApp group ID al que se enviará el mensaje. Ejemplos: 5411900001111, +5720900001111, +56 (56) 900001111.

String

recipientType

No

Debe ser "individual" o "group", dependiendo de si el campo destination es un número de teléfono o un group ID.

String

Mensaje:

CampoNecesarioDetallesTipo

messageText

Si

Campo utilizado en caso de que desee enviar un mensaje personalizado como respuesta a un mensaje recibido.

text

image

Si

Campo utilizado en caso de que desee enviar un contenido de imagen.

Image

audio

Si

Campo utilizado en caso de que desee enviar un contenido de audio.

Audio

document

Si

Campo utilizado en caso de que desee enviar un archivo o documento.

Document

contacts

Si

Campo utilizado en caso de que desee enviar contactos.

Contact[]

previewFirstUrl

No

Controla la vista previa de la aplicación de la primera URL enviada

Boolean

location

Si

Campo utilizado en caso de que desee enviar una ubicacion.

Location

Solo una de las siguientes opciones de midia debe ser especificado, ya sea ‘messageText’, ‘image’, ‘audio’, ‘document’, ‘location’ o ‘contacts’

Texto:

Solo se debe enviar un mensaje personalizado como respuesta a un mensaje recibido por el usuario siempre cuando la sesión se encuentre abierta. Si la sesión no está abierta o el usuario no envió un mensaje deberá utilizase el HSM.

Ejemplo de envío de texto

        {
            "destinations": [{
                "correlationId": "MyCorrelationId",
                "destination": "5519900001111"
            }],
            "message": {
                "messageText": "Mensaje de prueba"
            }
        }

Imagen:

CampoNecesarioDetallesTipo

type

Si

Tipo / extensión de la imagen que se enviará en el mensaje. Opciones disponibles: JPG, JPEG, PNG.

String

caption

No

Texto que se mostrara al usuario debajo de la imagen en Whatsapp

String

url

Si

URL donde se aloja el contenido que se enviará.

String

data

Si

Base64 contenido codificado

String

Ejemplo de envío de imagen (URL)

        {
            "destinations": [{
                "correlationId": "MyCorrelationId",
                "destination": "5519900001111"
            }],
            "message": {
                "image": {
                    "type": "JPG",
                    "url": "http://...jpg",
                    "caption": "image description"
                }
            }
        }

Ejemplo de envío de imagen (Base64)

{
           "destinations": [{
               "correlationId": "MyCorrelationId",
               "destination": "5519900001111"
           }],
           "message": {
               "image": {
                   "type": "JPG",
                   "data": "ZmlsZQ=="
               }
           }
       }

Solo se debe especificar una de las siguientes opciones, ya sea ‘url’, en caso de que desee enviar usando un archivo, o ‘datos’, en caso de que desee enviar una imagen usando la codificación base64

Audio:

CampoNecesarioDetallesTipo

type

Si

Tipo/Extensión de audio que se enviará en el mensaje. Opciones disponibles: AAC, MP4, AMR, MP3, OGG.

String

url

Si

URL donde se aloja el contenido que se enviará.

String

data

Si

Base64 contenido codificado

String

Solo se debe especificar una de las siguientes opciones, ya sea ‘url’, en caso de que desee enviar usando un archivo, o ‘datos’, en caso de que desee enviar un audio usando la codificación base64

Ejemplo de envío de audio (URL)

        {
            "destinations": [{
                "correlationId": "MyCorrelationId",
                "destination": "5519900001111"
            }],
            "message": {
                "audio": {
                    "type": "MP3",
                    "url": "http://...mp3"
                }
            }
        }

Ejemplo de envío de audio (Base64)

        {
            "destinations": [{
                "correlationId": "MyCorrelationId",
                "destination": "5519900001111"
            }],
            "message": {
                "audio": {
                    "type": "MP3",
                    "data": "ZmlsZQ=="
                }
            }
        }

Documento:

CampoNecesarioDetallesTipo

type

Si

Tipo/Extensión de documento que se enviará en el mensaje. Opciones disponibles: PDF.

String

caption

No

Texto que se mostrara al usuario debajo del documento en Whatsapp

String

url

Si

URL donde se aloja el contenido que se enviará.

String

data

Si

Base64 contenido codificado

String

Solo se debe especificar una de las siguientes opciones, ya sea ‘url’, en caso de que desee enviar usando un archivo, o ‘datos’, en caso de que desee enviar un documento usando la codificación base64 encoding

Ejemplo de envío de documento (URL)

        {
            "destinations": [{
                "correlationId": "MyCorrelationId",
                "destination": "5519900001111"
            }],
            "message": {
                "document": {
                    "type": "PDF",
                    "url": "http://...pdf",
                    "caption": "pdf description"
                }
            }
        }

Ejemplo de envío de documento (Base64)

        {
            "destinations": [{
                "correlationId": "MyCorrelationId",
                "destination": "5519900001111"
            }],
            "message": {
                "document": {
                    "type": "PDF",
                    "data": "ZmlsZQ=="
                }
            }
        }

Ejemplo de envío de ubicacion

        {
            "destinations": [{
                "correlationId": "MyCorrelationId",
                "destination": "5519900001111"
            }],
            "message": {
                "location": {
                    "geoPoint": "-22.894180,-47.047960",
                    "name": "Sinch",
                    "address": "Av. Cel. Silva Telles"
                }
            }
        }

Contact:

CampoNecesarioDetallesTipo

addresses

No

Direcciones de contacto completas.

Address[]

birthday

No

Fecha de cumpleaños como cadena con formato YYYY-MM-DD.

String

emails

No

Direcciones de correo electrónico de contacto.

Email[]

name

No

Nombre completo de contacto.

Name

org

No

Información de la organización de contacto.

Org

phones

No

Teléfonos de contacto.

Phone[]

urls

No

URLs de los contactos.

Url[]

Ejemplo de envio de contactos

        {  
           "destinations":[  
              {  
                 "correlationId":"MyCorrelationId",
                 "destination":"5519900001111"
              }
           ],
           "message":{  
              "contacts":[  
                 {  
                    "addresses":[  
                       {  
                          "city":"Menlo Park",
                          "country":"United States",
                          "country_code":"us",
                          "state":"CA",
                          "street":"1 Hacker Way",
                          "type":"HOME",
                          "zip":"94025"
                       },
                       {  
                          "city":"Menlo Park",
                          "country":"United States",
                          "country_code":"us",
                          "state":"CA",
                          "street":"200 Jefferson Dr",
                          "type":"WORK",
                          "zip":"94025"
                       }
                    ],
                    "birthday":"2012-08-18",
                    "emails":[  
                       {  
                          "email":"test@fb.com",
                          "type":"WORK"
                       },
                       {  
                          "email":"test@whatsapp.com",
                          "type":"WORK"
                       }
                    ],
                    "name":{  
                       "first_name":"John",
                       "formatted_name":"John Smith",
                       "last_name":"Smith"
                    },
                    "org":{  
                       "company":"WhatsApp",
                       "department":"Design",
                       "title":"Manager"
                    },
                    "phones":[  
                       {  
                          "phone":"+1 (940) 555-1234",
                          "type":"HOME"
                       },
                       {  
                          "phone":"+1 (650) 555-1234",
                          "type":"WORK",
                          "wa_id":"16505551234"
                       }
                    ],
                    "urls":[  
                       {  
                          "url":"https://www.fb.com",
                          "type":"WORK"
                       }
                    ]
                 }
              ]
           }
        }

Address:

CampoNecesarioDetallesTipo

street

No

Número y nombre de la calle.

String

city

No

Nombre de la ciudad.

String

state

No

Abreviatura del estado.

String

zip

No

Código postal.

String

country

No

Nombre completo del país.

String

country_code

No

Abreviatura de país de dos letras.

String

type

No

Valores estándar: HOME, WORK.

String

Email:

CampoNecesarioDetallesTipo

email

No

Correo electrónico.

String

type

No

Valores estándar: HOME, WORK.

String

Name:

CampoNecesarioDetallesTipo

first_name

No

Primer nombre.

String

last_name

No

Apellido.

String

middle_name

No

Segundo nombre.

String

name_suffix

No

Sufijo del nombre.

String

name_prefix

No

Prefijo del nombre.

String

formatted_name

No

Nombre completo como aparece normalmente.

String

Org:

CampoNecesarioDetallesTipo

company

No

Nombre de la empresa del contacto.

String

department

No

Nombre del departamento de contacto.

String

title

No

Título comercial de contacto.

String

Phone:

CampoNecesarioDetallesTipo

phone

No

Número de teléfono formateado.

String

type

No

Valores estándar: CELL, MAIN, IPHONE, HOME, WORK.

String

wa_id

No

Identificador de WhatsApp.

String

Url:

CampoNecesarioDetallesTipo

phone

No

URL del contacto.

String

type

No

Valores estándar: HOME, WORK.

String

Para los objetos que contienen un campo de tipo, los valores listados se consideran simplemente los valores estándar que se pueden ver, sin embargo, puede establecer el campo en cualquier valor descriptivo que elija..

Envío de mensajes HSM

Ejemplo de solicitud HSM

{
           "destinations": [{
               "correlationId": "MyCorrelationId",
               "destination": "5519900001111"
           }],
           "message": {
               "ttl": 1,
               "hsm": {
                   "namespace": "namespace",
                   "elementName": "elementName",
                   "parameters":[
                       "MyParam1",
                       "MyParam2"
                   ]
               }
           }
       }

También es posible enviar una base de mensajes en plantillas previamente definidas (también llamado HSM), con la adición de placeholders (“parámetros”). El cuerpo de la solicitud debe contener un objeto JSON con los siguientes campos:

CampoNecesarioDetallesTipo

destinations

Si

Lista de destinatarios

Destination

message

Si

Mensaje de texto que se enviará a la lista de destinatarios

Message

flowId

No

Identificación del flujo de Bot

String

defaultExtraInfo

No

Los datos adicionales que identifican el envío, se vincularán a todos los destinatarios que recibirán el mensaje

String

campaignAlias

No

ID de campaña, está vinculado a todos los mensajes del envío

String

Destino:

CampoNecesarioDetallesTipo

correlationId

No

Su id definido sera devuelto en un mensaje de confirmación (Callback). Esto será útil en casos en que se desea mantener el control del mensaje enviado, ya que es posible definir ids diferentes para mensajes distintos.

String

destination

Si

Número de teléfono al que se enviará el mensaje (código de país y estado deben estar presentes). Ejemplos: 5411900001111, +5720900001111, +56 (56) 900001111.

String

Mensaje:

CampoNecesarioDetallesTipo

ttl

No

Tiempo de vida en días. Define el número máximo de días en que el mensaje debe entregarse. Válido de 1 a 30. Valor predeterminado 7 si no está configurado.

long

hsm

Si

Contenido del mensaje HSM.

HSM

HSM:

CampoNecesarioDetallesTipo

namespace

Si

El espacio de nombres que se usará

String

elementName

Si

El nombre del elemento que indica qué plantilla usar dentro del espacio de nombres

String

parameters

Si, si la plantilla del mensaje tiene variables

Este campo es una matriz de valores para aplicar a las variables en la plantilla

String

languagePolicy

No

Parámetro que identifica cómo se seleccionará el lenguaje HSM. Opciones Disponibles: FALLBACK: Cuando la plantilla de HSM no tenga una versión para el idioma del dispositivo del usuario, se usará el idioma definido. DETERMINISTIC: El mensaje siempre se enviará en el código de idioma, independientemente del idioma en que esté configurado el dispositivo del usuario final.

String

languageCode

Obligatorio si languagePolicy está presente

Código de idioma o configuración regional, acepta ambos formatos: lenguaje (en) o lenguaje_local (es_AR). Para confirmar todos los idiomas disponibles para un HSM en particular, contáctese con nuestro equipo de Soporte.

String

Envío de mensajes template

Ejemplo de solicitud template

{
  {
    "destinations": [{
            "correlationId": "MyCorrelationId",
            "destination": "5519900001111"      
  }],
    "message": {
        "template": {
            "namespace" : "aaaaaaaa_bbbb_cccc_dddd_eeeeeeeeeeee",
            "elementName" : "some_approved_image_hsm",
            "header": {
                "image": {
                    "url": "https://upload.wikimedia.org/wikipedia/commons/c/c3/Arquivo.jpg",
                    "type": "JPG"
                }
            },
            "bodyParameters": [
                "https://upload.wikimedia.org/wikipedia/commons/c/c3/Arquivo.jpg"
            ],
            "languagePolicy": "DETERMINISTIC",
            "languageCode": "pt_BR"
        }
    }
}

También es posible enviar una base de mensajes en plantillas previamente definidas (también llamado templates), con la adición de placeholders (“parámetros”). El cuerpo de la solicitud debe contener un objeto JSON con los siguientes campos:

CampoNecesarioDetallesTipo

destinations

Si

Lista de destinatarios

Destination

message

Si

Mensaje de texto que se enviará a la lista de destinatarios

Message

flowId

No

Identificación del flujo de Bot

String

defaultExtraInfo

No

Los datos adicionales que identifican el envío, se vincularán a todos los destinatarios que recibirán el mensaje

String

campaignAlias

No

ID de campaña, está vinculado a todos los mensajes del envío

String

Destino:

CampoNecesarioDetallesTipo

correlationId

No

Su id definido sera devuelto en un mensaje de confirmación (Callback). Esto será útil en casos en que se desea mantener el control del mensaje enviado, ya que es posible definir ids diferentes para mensajes distintos.

String

destination

Si

Número de teléfono al que se enviará el mensaje (código de país y estado deben estar presentes). Ejemplos: 5411900001111, +5720900001111, +56 (56) 900001111.

String

Mensaje:

CampoNecesarioDetallesTipo

ttl

No

Tiempo de vida en días. Define el número máximo de días en que el mensaje debe entregarse. Válido de 1 a 30. Valor predeterminado 7 si no está configurado.

long

template

Si

Contenido del template del mensaje.

Template

Template:

CampoNecesarioDetallesTipo

namespace

Si

Valor que identifica la cuenta de registro del modelo de Facebook

String

elementName

Si

Valor que identifica el modelo registrado en Facebook

String

languageCode

Si

Uno de los idiomas definidos en el registro del template

String

languagePolicy

Si

Parámetro que identifica cómo se seleccionará el lenguaje HSM. Opciones Disponibles: FALLBACK: Cuando la plantilla de HSM no tenga una versión para el idioma del dispositivo del usuario, se usará el idioma definido. DETERMINISTIC: El mensaje siempre se enviará en el código de idioma, independientemente del idioma en que esté configurado el dispositivo del usuario final.

String

header

Si (caso lo template necessite)

Objetos de cabeçalho com sus parametros

Header

bodyParameters

Si (caso lo template use variaveis)

La suma de todos los caracteres del cuerpo, considerando los campos fijos y dinámicos, está limitada a 1024 caracteres si el template registrado solo tiene el cuerpo. Está limitado a 160 caracteres si tiene un header o footer.

Lista de strings

CampoNecesarioDetallesTipo

parameters

No

Lista de parámetros para reemplazar en el texto del header.

Si está presente, el header no debe tener title ni elements

title

No

El título debe tener hasta 60 caracteres.

String [ ]

element

Si

Opciones:

TEXT, IMAGE, AUDIO, DOCUMENT, HSM, VIDEO.

Obs.: No es obligatorio en caso de pasar el campo parameters

Object

Códigos comunes de respuesta de estado HTTP

Respuesta de envio exitoso (200)

Si tiene éxito, se espera una lista de destinatarios (“destinos”) con uuids generados desde el lado de la aplicación:

{
 "Id": "5efc3581-b8e8-11e7-9895-a6aabe61edb5",
  "destinations": [{
  "id": "5efc3581-b8e8-11e7-9895-a6aabe61edb5",
  "correlationId": "MyCorrelationId",
  "destination": "5519900001111."
}]
}

Respuesta de error de autenticación (401)

Si hay un problema en la autenticación del usuario, se espera el siguiente mensaje de error:

{
  "errorCode": 401,
  "errorMessage": "Authentication Error: No se encontró ningún usuario con esta combinación de nombre de usuario y token de autenticación."
}

Callback de actualización de estado

Ejemplo

{
  "total": 1,
  "data": [
    {
      "id": "8995c40f-1c3a-48d0-98ee-bbc603622a91",
      "correlationId": "...",
      "destination": "5411900000000",
      "origin": "5411900000000",
      "campaignId": 100,
      "campaignAlias": "...",