Documentação da API WhatsApp Now

Introdução

Bem-vindo à documentação da API WhatsApp Now do produto Message Central. Aqui você encontrará detalhes para aprender, testar e implementar cada um dos casos de uso da plataforma WhatsApp Business API. O WhatsApp Now é uma solução abrangente para integração com as APIs oficiais do WhatsApp Business. Nosso produto aproveita a plataforma WhatsApp robusta e amplamente usada para permitir que as empresas se comuniquem perfeitamente com seus clientes, fornecendo um serviço de mensagens confiável e eficiente.

Pré-requisitos para usar o WhatsApp Now

Antes de começar com a integração da API, certifique-se de ter:

1. Gerente de negócios do Facebook verificado
2. Conta na Central de Mensagens
3. Vinculação da sua conta comercial do Facebook com a Central de Mensagens
4. Um número de telefone que precisa ser verificado e usado com a Central de Mensagens

Ajuda e suporte

Para suporte de implementação e qualquer feedback, entre em contato conosco em operations@messagecentral.com

Entendendo as mensagens do WhatsApp

As mensagens do WhatsApp Business Solution só podem ser enviadas por empresas que tenham sido aprovadas pela Meta. Esse perfil comercial também terá uma etiqueta verde verificada para indicar que é uma empresa legítima.

A vantagem do WhatsApp é que o identificador dos usuários na plataforma é o número do celular.

Regras para clientes de mensagens

O WhatsApp tem o conceito de uma janela de atendimento ao cliente de 24 horas, durante a qual uma empresa pode enviar mensagens livremente a um usuário final. A janela de 24 horas pode ser iniciada de duas maneiras:

1. Um usuário final envia uma mensagem para a empresa
2. Uma empresa envia um modelo de mensagem para o usuário final. A janela de 24 horas começa assim que o usuário final responde.

Os modelos devem ser aprovados pela Meta antes de serem usados para enviar mensagens a um usuário final. Quando a janela de 24 horas expirar, uma nova janela de atendimento ao cliente de 24 horas deverá ser iniciada novamente. É importante estar ciente de que as janelas de atendimento ao cliente de 24 horas não são iguais à janela de conversa faturável de 24 horas.

Preços baseados em conversas do WhatsApp

A Central de Mensagens oferece um modelo de preços baseado em conversas para mensagens do WhatsApp. Isso está de acordo com o modelo de preços introduzido pelo WhatsApp no início de fevereiro de 2022.

O que é uma conversa?

Uma conversa é qualquer número de mensagens enviadas em uma “sessão”, que é definida como um período de 24 horas a partir do momento em que a primeira mensagem é enviada pela empresa.

Quem inicia uma conversa?

Uma conversa pode ser iniciada seja por um cliente (iniciado pelo usuário) ou negócio (iniciada pela empresa), mas em ambos os casos a “sessão” começa com a primeira mensagem enviada pela empresa.

Como funciona o preço por conversa?

O preço das mensagens do WhatsApp é por conversa. A partir de 1º de junho, esse preço é cobrado por conversa e tipo de conversa. Agora existem quatro categorias de conversação, cada uma das quais é cobrado com taxas diferentes:

1. Conversa utilitária - Permitir a conclusão de uma solicitação ou transação específica acordada ou fornecer ao cliente uma atualização sobre uma transação em andamento, incluindo notificações pós-compra e extratos de cobrança regulares.
2. Conversa sobre autenticação - Permite que as empresas utilizem senhas únicas para verificar usuários em vários estágios de login, se necessário (por exemplo, verificação de conta, recuperação de conta, desafios de integridade)
3. Conversa de marketing - Conversas iniciadas por empresas para comercializar um bem ou serviço aos clientes, como o envio de ofertas pertinentes aos clientes que optaram por participar. Isso também incluiria qualquer interação relacionada a negócios que não seja uma conversa sobre autenticação ou utilidade.
4. Conversa de serviço - Discussões iniciadas pelo usuário que ajudam os consumidores a obter respostas para suas perguntas.

APIs do WhatsApp Now

A Central de Mensagens facilita o envio de mensagens por vários canais de comunicação, incluindo SMS, WhatsApp, RCS (Rich Communication Services). Essa API fornece recursos robustos e opções flexíveis para atender às diversas necessidades de mensagens. O WhatsApp Now é um produto da Central de Mensagens baseado nas APIs oficiais do WhatsApp Business.

Cenários de casos de uso

• Campanhas promocionais: Use o WhatsApp Now para enviar mensagens promocionais e utilitárias aos clientes via WhatsApp. Envie multimídia e documentos diretamente pelo WhatsApp. Entregue mensagens, notificações e atualizações personalizadas para aumentar a satisfação e a fidelidade do cliente e aprimorar a experiência do cliente.
  
• Mensagens de bate-papo ao vivo: Envie e receba mensagens, multimídia e documentos diretamente pelo WhatsApp, garantindo uma comunicação oportuna e eficaz com seu público.
  
• Verificação OTP: implemente um sistema seguro de entrega OTP para autenticação do usuário, escolhendo entre SMS, WhatsApp ou e-mail com base nas preferências do usuário e nos requisitos de segurança.

Além disso, os seguintes parâmetros precisam ser enviados ao usar as APIs do WhatsAppNow;

URLs básicos da API Rest:

Todos os endpoints da API da plataforma abaixo devem ser prefixados com o seguinte URL:

https://cpaas.messagecentral.com

Gerar token

Ao usar as APIs do WhatsApp Now para criar modelos, enviar mensagens de texto e transmitir mensagens, a chamada inicial deve ser para a API de geração de tokens. Essa API retorna um token que deve ser incluído em todas as chamadas subsequentes. É necessário um token de autenticação para validar o usuário e deve ser incluído na seção de cabeçalho de cada solicitação.

Parâmetros da solicitação:

Caminho do URL da solicitação:

/auth/v1/authentication/token 

cURL

1curl --location 'https://cpaas.messagecentral.com/auth/v1/authentication/token?customerId=<CustomerId>&key=<Base64 Encrypted password>&scope=NEW&country=91&email=test@messagecentral.com' \
2--header 'accept: */*'

‍

NOTA: Para converter um comando cURL em código usando o Postman, abra o Postman, importe o comando cURL por meio do botão “Importar” e gere o código no idioma de sua preferência clicando no botão “Código” no lado direito da solicitação.

Resposta JSON

Uma resposta bem-sucedida retornará um código de status 200.

1{
2      "status": Integer,
3      "token": "String"
4} 

Criar modelo

Você pode criar modelos de vários tipos e categorias, bem como criar várias variações de idioma de um modelo. Ao criar modelos com versões em vários idiomas, certifique-se de ser consistente com as traduções em todas as versões.

Certifique-se de que seus modelos sigam Diretrizes de modelos de mensagens do WhatsApp. Não seguir corretamente as diretrizes pode afetar a aprovação dos modelos.

‍

Processo de aprovação

Os modelos precisam ser aprovados pela Meta antes de serem usados em uma mensagem do WhatsApp. Quando criados, os modelos inicialmente têm um status de PENDENTE. Uma vez aprovados, eles terão um status de APROVADO, e pode então ser usado.

Categorias de modelos

• UTILIDADE: permita a conclusão de uma solicitação ou transação específica acordada ou forneça ao cliente uma atualização sobre uma transação em andamento, incluindo notificações pós-compra e extratos de cobrança regulares.
• AUTENTICAÇÃO: permite que as empresas utilizem senhas únicas para verificar usuários em vários estágios de login, se necessário (por exemplo, verificação de conta, recuperação de conta, desafios de integridade).
• MARKETING: conversas iniciadas por empresas para comercializar um bem ou serviço aos clientes, como o envio de ofertas pertinentes aos clientes que optaram por participar. Isso também incluiria qualquer interação relacionada a negócios que não seja uma conversa sobre autenticação ou utilidade.

Para Criar modelo abaixo estão os parâmetros da solicitação. O token de autenticação é necessário para criar um modelo que é gerado pela API do token gerado (que você pode encontrar acima na seção Introdução)

Caminho do URL da solicitação:

POST: /verification/v3/template

Parâmetros da solicitação:

cURL

1curl --location 'https://cpaas.messagecentral.com/verification/v3/template' \
2--header 'authToken: eyJhbGciOiJIUzUxMiJ9.eyJzdWIiOiJDLTM4MERBQzg1RDlGRjREMSIsImlhdCI6MTcyMDc2OTI2OCwiZXhwIjoxODc4NDQ5MjY4fQ.O8xl7vMUoOU4dCn61dqFTjBMxTVvnEpRCkzjMo4JW9YQrEdL0PK3sQW4PgZBWRUCvKDkoSRoDAdXhXy9rx' \
3--form 'phoneNumber="919457888189"' \
4--form 'name="template_without_media"' \
5--form 'language="en_US"' \
6--form 'category="MARKETING"' \
7--form 'headerFormat="TEXT"' \
8--form 'header="Congratulations"' \
9--form 'body="Hello Your account recharge of ₹100 is successful. Please use our services and enjoy!"' \
10--form 'footer="Type \"STOP\" to unsubscribe"'

‍

cURL

1curl --location 'https://cpaas.messagecentral.com/verification/v3/template' \
2--header 'authToken: eyJhbGciOiJIUzUxMiJ9.eyJzdWIiOiJDLTM4MERBQzg1RDlGRjREMSIsImlhdCI6MTcyMDc2OTI2OCwiZXhwIjoxODc4NDQ5MjY4fQ.O8xl7vMUoOU4dCn61dqFTjBMxTVvnEpRCkzjMo4JW9YQrEdL0PK3sQW4PgZBWRUCvKDkoSRoDAdXYh9rxa' \
3--form 'phoneNumber="919457888189"' \
4--form 'name="template_without_media"' \
5--form 'language="en_US"' \
6--form 'category="MARKETING"' \
7--form 'headerFormat="TEXT"' \
8--form 'body="Hello Your account recharge of ₹100 is successful. Please use our services and enjoy!"' \
9--form 'footer="Type \"STOP\" to unsubscribe"' \
10--form 'file=@"/C:/Users/Kunal Suryawanshi/Downloads/Media (9).png"'

‍

Resposta JSON (sem e com modelos de mídia):

Uma resposta bem-sucedida retornará um código de status 200.

1{
2    "responseCode": 200,
3    "data": {
4        "data": {
5            “name”: "example_template",
6            "id": "790937216444187",
7            "status": "PENDING",
8            "category": "MARKETING"
9        }
10    }
11}

Consultoria para criar um modelo

1. Nome - O nome do modelo deve estar sempre em letras minúsculas. Além disso, no caso de várias palavras, adicione um “_” entre 2 palavras (por exemplo: tes_template_01)
2. Modelo de variável - Para criar um modelo de variável, você precisa adicionar marcadores de posição e seus valores corporais obrigatoriamente ao criar uma solicitação para esse modelo.

Variáveis - Eles são sempre adicionados em duas chaves encaracoladas e em números crescentes
faça o pedido, caso contrário, seu modelo será rejeitado.
Valor corporal - Esses são exemplos do que estará dentro dos valores das variáveis. Desde
esses são dados do formulário, portanto, no caso de mais de 2 variáveis, separe-os por
espaços.

‍Exemplo de mensagem - Olá {{1}}, ganhe 50% de desconto aplicando o código de cupom {{2}} mais recente até {{3}}

BodyValue (para a mensagem acima) - “Kunal MSGCTL50 20thJune”, aqui Kunal é um exemplo de 1st BodyValue e assim por diante.

3. Limite de caracteres - Uma mensagem de texto pode ter no máximo 4096 caracteres longos.

Códigos de erro para criar modelo

Verifique o status do modelo

Isso permite que você monitore o status dos seus modelos de mensagens enviados para aprovação no WhatsApp. Essa API fornece atualizações em tempo real sobre se seus modelos estão aprovados, pendentes ou rejeitados, garantindo que você se mantenha informado sobre sua disponibilidade para uso.

Parâmetros da solicitação:

cURL

1curl --location --request GET 
2'https://cpaas.messagecentral.com/verification/v3/template' \
3--header 'authToken: 
4eyJhbGciOiJIUzUxMiJ9.eyJzdWIiOiJDLTM4MERBQzg1RDlGRjREMSIsImlhdCI6MTcyMDc2OT
5 I2OCwiZXhwIjoxODc4NDQ5MjY4fQ.O8xl7vMUoOU4dCn61dqFTjBMxTVvnEpRCkzjMo4JW9YQrE
6 dL0PK3sQW4PgZBWRUCvKDkoSRoDAdYXh9rxa' \
7 --form 'phoneNumber="919547888189"' \
8 --form 'templateId="205681076471259"' \
9 --form 'templateName="test_template"' 

‍

Resposta JSON

Uma resposta bem-sucedida retornará um código de status 200.

1{
2    "name": "prod_test_temp_wmedia_1",
3    "components": [
4        {
5            "type": "HEADER",
6            "format": "TEXT",
7            "text": "Congratulations!"
8        },
9        {
10            "type": "BODY",
11            "text": "Your account recharge of $100 is successful. Please use our services and enjoy!"
12        },
13        {
14            "type": "FOOTER",
15            "text": "Type \"STOP\" to unsubscribe"
16        }
17    ],
18    "language": "en_US",
19    "status": "APPROVED",
20    "category": "UTILITY",
21    "id": "205681076471259"
22}

Códigos de erro para obter status do modelo

Enviar transmissão

Para enviar uma transmissão do WhatsApp para números de celular, os seguintes parâmetros de solicitação são necessários. Um token de autenticação, gerado pela API de geração de token, é necessário para enviar as mensagens do modelo via transmissão.

Caminho do URL da solicitação:

POST: /verification/v3/send

Enviar transmissão única

Para enviar uma mensagem de transmissão do WhatsApp para um único destinatário para divulgação personalizada, respostas de suporte ao cliente ou notificações urgentes quando a comunicação direcionada é necessária.

Parâmetros da solicitação:

NOTA: Os modelos usados devem ser APROVADOS pela Meta. No máximo 2 CTAs dinâmicos só podem ser enviados.

cURL

NOTA: Todos os modelos usados devem ser modelos APROVADOS da Meta.

Encontre o formato de arquivo de amostra no formato XLXS abaixo:

Descrições de campo:

NOTA: As primeiras quatro colunas (Country, Mobile, CTAvar1, CTAvar2) deve sempre ser incluído no cabeçalho, mesmo que não haja CTAs dinâmicos no modelo. Nesses casos, os nomes das colunas devem permanecer, mas os valores devem ser deixados em branco.

O número de variável as colunas no arquivo do Excel devem corresponder exatamente ao número de espaços reservados variáveis em seu modelo. Por exemplo, se seu modelo contiver dois espaços reservados, seu arquivo deverá incluir var1 e var2—nem mais, nem menos.

Consulte os exemplos a seguir para entender a formatação correta do arquivo.

Exemplo 1: Se uma empresa quiser enviar uma mensagem personalizada usando o upload de arquivos sem CTA dinâmico e 2 variáveis, o campo da mensagem deve ser formatado da seguinte forma:

Exemplo de mensagem - Olá {{1}}, ganhe 50% de desconto aplicando o cupom {{2}} O formato XLxS deve ser o seguinte:

Exemplo 2: Se uma empresa quiser enviar uma mensagem personalizada usando o upload de arquivos com CTA dinâmico e 3 variáveis, o campo da mensagem deve ser formatado da seguinte forma:

Exemplo de mensagem - Olá {{1}}, ganhe 50% de desconto aplicando o cupom {{2}} mais recente de {{3}} CTA - www.messagecentral.com/ {{1}}

O formato XLxS deve ser o seguinte:

cURL

1curl --location 
2'https://cpaas.messagecentral.com/verification/v3/send?flowType=WHATSAPP&se
3 nderId=919457848169&type=BROADCAST&templateName=template_without_media_1' \
4 --header 'authToken: 
5eyJhbGciOiJIUzUxMiJ9.eyJzdWIiOiJDLTM4MERBQzg1RDlGRjREMSIsImlhdCI6MTcyMDc2OT
6 I2OCwiZXhwIjoxODc4NDQ5MjY4fQ.O8xl7vMUoOU4dCn61dqFTjBMxTVvnEpRCkzjMo4JW9YQrE
7 dL0PK3sQW4PgZBWRUCvKDkoSRoDAdYXh9rxa' \
8 --form 'file=@"/C:/Users/Kunal Suryawanshi/Documents/Test_WA_API.xlsx"'

‍

Resposta JSON

Uma resposta bem-sucedida retornará um código de status 200.

1{
2    "responseCode": 200,
3    "message": "SUCCESS",
4    "data": null
5}
6

Códigos de erro para enviar transmissão

Enviar mensagens de bate-papo

Para enviar uma mensagem do WhatsApp (mensagem de bate-papo) para um número de celular, os seguintes parâmetros de solicitação são necessários. Um token de autenticação, gerado pela API de geração de tokens, é necessário para enviar qualquer mensagem pelo chat ao vivo.

Caminho do URL da solicitação:

/verification/v3/send

Parâmetros da solicitação:

cURL

1curl --location --request POST 'https://cpaas.messagecentral.com/verification/v3/send?countryCode=91&flowType=WHATSAPP&mobileNumber=7715836906&senderId=919457888189&type=CHAT&message=Welcome%20to%20Message%20Central' \
2--header 'authToken: eyJhbGciOiJIUzUxMiJ9.eyJzdWIiOiJDLTM4MERBQzg1RDlGRjREMSIsImlhdCI6MTcyMDc2OTI2OCwiZXhwIjoxODc4NDQ5MjY4fQ.O8xl7vMUoOU4dCn61dqFTjBMxTVvnEpRCkzjMo4JW9YQrEdL0PK3sQW4PgZBWRUCvKDkoSRoDAdYXh9rxa'

‍

Resposta JSON

Uma resposta bem-sucedida retornará um código de status 200.

1{
2    "responseCode": 200,
3    "message": "SUCCESS",
4    "data": {
5        "verificationId": null,
6        "mobileNumber": "917715836906",
7        "responseCode": "200",
8        "errorMessage": null,
9        "timeout": null,
10        "smsCLI": null,
11        "transactionId": "wamid.HBgMOTE3NzE1ODM2OTA2FQIAERgSOEFFNUM5MTFDRUVBMDUzMDFGAA=="
12    }
13}

Códigos de erro para mensagens de bate-papo

Configurar webhook para mensagens de entrada

Antes de começar a receber notificações, você precisará criar um endpoint no seu servidor para receber notificações.

Sempre que ocorre um evento acionador, a plataforma WhatsApp Business da Central de Mensagens vê o evento e envia uma notificação para um URL de webhook que você especificará. Você pode receber dois tipos de notificações:

1. Mensagens recebidas: Esse alerta permite que você saiba quando você recebeu uma mensagem. Elas também podem ser chamadas de “notificações de entrada” em toda a documentação.
2. Status da mensagem: Esse alerta permite que você saiba quando o status de uma mensagem foi alterado — por exemplo, a mensagem foi lida ou entregue. Elas também podem ser chamadas de “notificações de saída”.

Para assinar o Webhooks, você precisará seguir estas etapas:

1. Informações necessárias:algum texto
   1. ID do cliente
   2. Nome da marca
   3. ID de e-mail registrado
   4. URL de retorno de chamada
      
      
2. Instruções de envio: Envie as informações acima para operations@messagecentral.com com a linha de assunto “Configuração de webhook do WhatsApp com a Central de Mensagens”.
   
   
3. Especificações do URL de retorno de chamada: certifique-se de que seu URL de retorno de chamada esteja acessível e seja capaz de receber solicitações HTTP POST contendo cargas JSON com atualizações de status. Ao ser acionado, o endpoint receberá a seguinte carga JSON e deverá responder com 200.

‍