NAV Navbar

en es pt

API HTTP WhatsApp

Esta documentação prove as infomações necessárias para a integração com a plataforma do ChatClub para realizar o envio de mensagens através da integração Wavy WhatsApp Integration, assim como as informações para recebimento de status de notificação (Callback - WebHook). A plataforma do ChatClub permite o envio de mensagens únicas ou em lote. A API possui integração REST, utilizando o protocolo HTTP com TLS, suportando o método POST com os parametros enviados em formato JSON.

User Autenticação

Para utilizar com sucesso a nossa API, é preciso apresentar um username válido, ou email, associado com um token de autenticação. É preciso adicionar os seguintes headers a requisição:

Campo Detalhes Data Type
UserName Nome ou email válido para autenticação no ChatClub. String
AutenticaçãoToken Token de autenticação gerado por nossa plataforma. Encontre aqui ou consulte nosso suporte. here String

Connection Detalhes

Hostname api-messaging.movile.com
Porta 443 (https)
Protocolo HTTPS (TLS encryption)
Autenticação username + token
Encoding UTF-8

Envio de Mensagens

Envio de Mensagens de Texto

Exemplo de requisição com Imagem (URL)

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

Exemplo de requisição com Imagem (Base64)

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

Exemplo de requisição com Audio (URL)

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

Exemplo de requisição com Audio (Base64)

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

Exemplo de requisição com Documento (URL)

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

Exemplo de requisição com Documento (Base64)

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

Permite o envio de mensagens através da plataforma de WhatsApp para um ou mais destinos.

POST https://api-messaging.movile.com/v1/whatsapp/send

A requisição precisa conter um objeto JSON no corpo com os seguintes campos:

Campo Obrigatório Detalhes Tipo
Destinos Sim Lista de Destinos Destino[]
mensagem Sim Mensagem de Texto que será enviada a todos os destinos mensagem
flowId Não Identificador de Fluxo do Bot String
defaultExtraInfo Não Dados adicionais que identifiquem o envio, serão vinculados a todos os destinatários que receberão a mensagem String
campaignAlias Não ID da campanha, é linkado com todas as mensagens enviadas String
previewFirstUrl No Controla a exibição no app da primeira URL enviada ao usuário Boolean

Destino:

Campo Obrigatório Detalhes Tipo
correlationId Não Id definido por voce que será retornado na configuração da mensagem (callback). Isto é útil em casos quando é necessário rastear os envios das mensagens, pois é possivel definir ids diferentes para diferentes mensagens. String
Destino Sim Número de telefone que receberá a mensagem (código do país (55 para Brasil) e DDD devem estar presentes).Exemplos:5519900001111, +5519900001111, +55(19) 900001111. String

mensagem:

Campo Obrigatório Detalhes Tipo
image Sim Campo utilizado quando for necessário o envio de uma imagem. Image
audio Sim Campo utilizado quando for necessário o envio de uma áudio. Audio
document Sim Campo utilizado quando for necessário o envio de uma documento. Document

Imagem:

Campo Obrigatório Detalhes Tipo
tipo Sim Tipo/extensão da imagem que será enviada na mensagem. Opções disponiveis: JPG, JPEG, PNG. String
caption Não Texto que será apresentado ao usuário embaixo da imagem String
url Sim URL que hospeda o arquivo a ser enviado. String
data Sim conteúdo encodado em Base64 String

Audio:

Campo Obrigatório Detalhes Tipo
type Sim Tipo/extensão do audio que será enviado na mensagem. Opções disponiveis: AAC, MP4, AMR, MP3, OGG. String
url Sim URL que hospeda o arquivo a ser enviado. String
data Sim conteúdo encodado em Base64 String

Documento:

Campo Obrigatório Detalhes Tipo
type Sim Tipo/extensão do documento que será enviado na mensagem. Opções disponiveis: PDF. String
url Sim URL que hospeda o arquivo a ser enviado. String
data Sim conteúdo encodado em Base64 String

Mandando mensagens HSM

Exemplo requisição HSM

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

É possivel também enviar mensagens baseadas em templates definidos anteriormente (também chamado de HSM). Com a adição dos placeholders (“parametros”). O corpo da requisição tem que conter um objeto JSON com os seguintes campos:

Campo Obrigatório Detalhes Tipo
Destinos Sim Lista de Destinos Destino[]
mensagem Sim Mensagem de texto que será enviada para a lista de Destinos mensagem
flowId Não Identificação do fluxo do Bot String
defaultExtraInfo Não Dados adicionais que identifiquem o envio, serão vinculados a todos os destinatários que receberão a mensagem String
campaignAlias Não ID da campanha, é linkado com todas as mensagens enviadas String

Destino:

Campo Obrigatório Detalhes Tipo
correlationId Não Id definido por voce que será retornado na configuração da mensagem (callback). Isto é útil em casos quando é necessário rastear os envios das mensagens, pois é possivel definir ids diferentes para diferentes mensagens. String
Destino Sim Número de telefone que receberá a mensagem (código do país (55 para Brasil) e DDD devem estar presentes).Exemplos:5519900001111, +5519900001111, +55(19) 900001111. String

mensagem:

Campo Obrigatório Detalhes Type
hsm Sim Conteudo da mensagem HSM HSM

HSM:

Campo Obrigatório Detalhes Tipo
namespace Sim O namespace que será usado String
elementName Sim O Nome do elemento que indica qual template (HSM) será usado com o namespace String
parameters Sim Se o template possivel variaveis Este campo é um array de valores para aplicar as variaveis do template
languagePolicy Não Parametro que identifica como a linguagem HSM será selecionada. Opções disponiveis:\nFALLBACK: Quando a template HSM não tem uma versão para a linguagem do aparelho do usuário, a linguagem definida deverá ser usada. \nDETERMINISTIC: A mensagem será sempre enviada com o código da linguagem, independente da linguagem do aparelho do usuário final. String
languageCode Mandatório se a languagePolicy esta presente Language code ou locale, é aceito os dois formatos: linguagem (en) ou language_locale (pt_BR). Para confirmar todas as linguagens disponiveis para um HSM em particular entre em contato com nosso time de suporte. String

HTTP Status Code Response Comuns

Request response com sucesso (200)

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

Se a requisição for executada com sucesso, a lista de destinos com os uuids gerados será retornado:

Autenticação error response (401)

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

Se ocorrer um problema com a autenticação, a seguinte mensagem será retornada:

Atualização de status Callback

Example

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

Toda atualização do status de mensagens enviadas (confirmação de entrega ao usuário final, leitura da mensagem, etc), um callback/webhook é enviado. Callbacks são enviados em lote.

Importante: O endpoint em que o webhook utilizará para enviar os status precisa ser configurado por nosso time de suporte e operações.

O formato do retorno seguirá a seguinte descrição:

Campo Obrigatório Detalhes Tipo
total Número de callbacks na ligação. String
data Lista de Callbacks. Data[]

Dados:

Campo Obrigatório Detalhes Tipo
id Último id da mensagem. String
correlationId Um ID unico definido por voce para comparar com o status da mensagem (Callback and DLR). Este parametro é opcional, e voce pode usar o ID gerado pelo ChatClub para fazer a comparação. String
destination Número de telefone que a mensagem foi enviada (incluindo código de pais). Exemplo: 5511900000000. String
origin Número de telefone que identifica a Conta de WhatsApp (incluindo código de pais). Exemplo: 5511900000000. String
campaignId campaignID definido anteriormente. String
campaignAlias Campaign alias definido anteriormente. String
extraInfo Informação extra enviada com a mensagem original. String
sent Indica se a mensagem foi enviada. Boolean
sentStatusCode Code de Status gerado pelo ChatClub para a mensagem indicando o status de envio. Number
sentStatus Descrição do status de envio. Boolean
sentDate Data em que a mensagem foi enviada. formato: yyyy-MM-dd’T'HH:mm:ssZ. String
sentAt Tempo em que a mensagem foi enviada, usando Unix_time format Number
delivered Indica se a mensagem foi entregue no destino. Boolean
deliveredStatusCode Código de Status gerado pelo ChatClub indicando se a mensagem foi entregue. Number
deliveredStatus Descrição do status de entrega. String
deliveredDate Data em que a mensagem foi entregue. formato:: yyyy-MM-dd’T'HH:mm:ssZ String
deliveredAt Tempo em que a mensagem foi entregue, usando Unix_time format Number
read Indica se a mensagem foi lida pelo destinatário. Boolean
readDate Data em que a mensagem foi lida. formato: yyyy-MM-dd’T'HH:mm:ssZ String
readAt Tempo em que a mensagem foi lida, usando Unix_time format String
updatedDate Data em que o status da mensagem foi atualizado. Formato: yyyy-MM-dd’T'HH:mm:ssZ String
updatedAt Data em que o status da mensagem foi atualizado, usando Unix_time format String

MO (mensagem enviadas pelo usuário final para a conta do Whatsapp)

Exemplo de mensagem de texto:

{
  "total": 1,
  "data": [
    {
      "id": "ce425ffe-bc62-421f-9261-e6819a5eab43",
      "source": "5519900000000",
      "origin": "5519900000000",
      "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"
    }
  ]
}

Exemplo de mensagem de midia

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

Exemplo de mensagem de localização:

{
  "total": 1,
  "data": [
    {
      "id": "ce425ffe-bc62-421f-9261-e6819a5eab43",
      "source": "5519900000000",
      "origin": "5519900000000",
      "campaignId": 100,
      "correlationId": "...",
      "campaignAlias": "...",
      "flowId": "....",
      "extraInfo": "...",
      "message": {
            "type": "LOCATION",
"location": "lat,lng"
      },
      "receivedAt": 1513616971473,
      "receivedDate": "2017-12-18T17:09:31.473Z"
    }
  ]
}

Cada resposta do usuário final (MO ou Mobile Originated) um callback/webhook é enviado. Essas MOs são enviadas em lote.

Importante: O endpoint em que o webhook utilizará para enviar os status precisa ser configurado por nosso time de suporte e operações.

O formato do retorno seguirá a seguinte descrição:

Campo Detalhes Tipo
total Números de callbacks para a ligação. String
data Lista de mensagens Mobile Originated (MO). Data[]
Campo Detalhes Tipo
id Última identificação da mensagem String
source Número de telefone do remetente String
origin Número de telefone que identifica a Conta de WhatsApp (incluindo código de pais). Exemplo: 5511900000000. String
correlationId Um ID unico definido por voce para comparar com o status da mensagem (Callback and DLR). Este parametro é opcional, e voce pode usar o ID gerado pelo ChatClub para fazer a comparação. String
campaignId campaignID definido anteriormente. String
campaignAlias Campaign alias definido anteriormente. String
mensagem Mensagem MO. mensagem
receivedAt Data em que a mensagem foi recebida. Format: yyyy-MM-dd’T'HH:mm:ssZ String
receivedDate Data em que a mensagem foi recebida, usando Unix_time format String

mensagem:

type Tipo de mensagem enviada para o usuário final: TEXT - IMAGE - AUDIO - DOCUMENT
messageText A mensagem de texto (MO) enviada pelo usuário final.
mediaUrl Url para download da midia enviada pelo usuário final.
mimeType Mime type do arquivo enviado pelo usuário final.
caption Media label enviada pelo usuário final.
location Localidade enviada pelo usuário final. formato: “latitude,longitude”

API SFTP WhatsApp

Detalhes de conexão

Hostname ftp-messaging.movile.com
Porta 2222
Protocolo SFTP (transferência sobre ssh, provendo criptografia entre cliente-servidor)
Autenticação username + senha (fornecido pelo suporte)

Envio de mensagem via SFTP

Para realizar o disparo de mensagens via FTP é necessário gerar um arquivo com a formatação seguindo o exemplo abaixo: Mensagem HSM:

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

1ª Linha
Data de envio (para casos de agendamento)
Hora inicial de envio (para casos de agendamento)
Hora final de envio (para casos de agendamento)
Tipo de mensagem deve ser: HSM
Nome (elementName) do HSM
Idioma (languageLocale) do HSM
Determinístico ou Fallback do idioma do HSM (languagePolicy)
nome dos parâmetros do HSM

Observações para primeira linha:

1 - Os nomes dos parâmetros devem coincidir com os nomes das colunas

2 - As informações que não forem ser utilizadas podem ser deixadas em branco, porém devem manter o ponto e vírgula como separação. Exemplo de um caso que não utilizamos agendamento (os campos iniciais ficam entre ponto e vírgula e sem informação dentro):  ; ; ; HSM;chatclub_welcome;pt_BR;DETERMINISTIC;nome|empresa

3 - Por default (padrão) a languagePolicy será Determinístico.

4 - Os nomes dos parâmetros do HSM devem ser separados por “ | ” e não por “ ; ”

2ª Linha
Nome das colunas
3ª e demais linhas:
Destinatário e valores dos parâmetros do HSM