Pular para o conteúdo principal

Ambiente de testes para contatos com nome de usuário compartilhado

  • Atualizado

  1. Visão geral

  2. Endpoint

  3. Campos da requisição

  4. Regras

  5. Requisição

  6. Estrutura do payload

  7. Quando utilizar

  8. Possíveis erros

  9. Considerações

 

Visão geral

A Blip está disponibilizando um endpoint para realizar o cadastro de contatos que serão usados para testes associados a um número de telefone no WhatsApp. Nesse cenário de teste, o contato cadastrado se comporta como um contato que adotou o recursos e Nome de usuário e que, por isso, não compartilha o número de telefone. Esse contato será criado tendo um GUID como identidade do contato.

O endpoint permite informar os dados básicos do contato, como nome de exibição e número de telefone, por meio de uma requisição set direcionada ao recurso /phone-numbers/test-contacts.

Esse recurso pode ser utilizado em cenários em que seja necessário configurar ou atualizar contatos de teste para validação de integrações e funcionalidades relacionadas ao nome de usuário do WhatsApp.

 

Endpoint

A operação é realizada por meio do endpoint de comandos da organização:

POST https://{ORGANIZATION_ID}.http.msging.net/commands

Headers

Content-Type: application/json
Authorization: Key {YOUR_TOKEN}

Onde:

  • ORGANIZATION_ID: identificador da organização/conta na Blip.

  • YOUR_TOKEN: chave de autorização do bot utilizada para realizar a requisição.
     

Campos da requisição

A requisição utiliza o formato de comando da plataforma Blip.

Campo Descrição
id Identificador único da requisição. Pode ser gerado automaticamente, por exemplo, utilizando {{$guid}}.
to Destinatário do comando. Para essa operação, deve ser utilizado postmaster@wa.gw.msging.net.
method Método da operação. Para cadastro ou atualização do contato, deve ser utilizado set.
type Tipo do recurso enviado na requisição. Deve ser application/vnd.iris.whatsapp.phonenumber+json.
uri Recurso que será manipulado. Para contatos de teste, deve ser /phone-numbers/test-contacts.
resource Objeto contendo os dados do contato de teste.
resource.displayName Nome de exibição do contato de teste. (não obrigatório)
resource.number Número de telefone associado ao contato.

 

Regras

Para que um número possa ser cadastrado como Test Contact, algumas regras devem ser respeitadas:

  • O número deve ser novo, ou seja, ainda não deve estar cadastrado como Test Contact.

  • É permitido cadastrar no máximo 2 números como Test Contacts.

  • O número não pode ter sido utilizado anteriormente para conversar com o Bot.

  • O número deve ser informado no formato internacional, incluindo o código do país. Exemplo: +5511999999999

⚠️ Importante: não é possível excluir um número do ambiente de teste. Depois que o número é adicionado, ele sempre vai se comportar como um número criado como Guid. Esse estado não pode ser revogado.
 

Requisição

Exemplo de requisição para cadastrar um contato de teste:

POST https://{ORGANIZATION_ID}.http.msging.net/commands HTTP/1.1
Content-Type: application/json
Authorization: Key {YOUR_TOKEN}
{
    "id": "{{$guid}}",
    "to": "postmaster@wa.gw.msging.net",
    "method": "set",
    "type": "application/vnd.iris.whatsapp.phonenumber+json",
    "uri": "/phone-numbers/test-contacts",
    "resource": {
        "displayName": "teste",
        "number": "+5511999999999"
    }
}

Exemplo dos dados utilizados

No exemplo acima:

  • Nome do contato: teste

  • Número: +5511999999999

  • Método: set

  • Recurso: /phone-numbers/test-contacts

O número deve ser informado no formato internacional, incluindo o código do país.
 

Estrutura do payload

O objeto resource concentra as informações do contato que será configurado:

"resource": {
    "displayName": "teste",
    "number": "+5511999999999"
}

displayName (não obrigatório)

Representa o nome de exibição associado ao contato de teste.

Exemplo:

"displayName": "teste"

number

Representa o número de telefone do contato no formato +DDI_DDD_NÚMERO

Exemplo:

"number": "+5511999999999"

Recomenda-se informar o número utilizando o formato internacional, incluindo o + e o código do país.
 

Quando utilizar

O endpoint pode ser utilizado em cenários em que é necessário configurar contatos de teste sem número de telefone conhecido relacionados a números de telefone do WhatsApp, por exemplo:

  • Testes de funcionalidades relacionadas ao WhatsApp;

  • Configuração de contatos utilizados em ambientes de teste;

  • Automação do cadastro de contatos de teste;

  • Atualização dos dados de um contato de teste.

Ponto de atenção: substitua {ORGANIZATION_ID} pela organização correspondente e {YOUR_TOKEN} por uma chave de autorização válida antes de realizar a chamada.
 

Possíveis erros

Durante a utilização do endpoint /phone-numbers/test-contacts, algumas situações podem impedir o cadastro do contato de teste.

1. Contact cannot be registered as test contact

Descrição:

Esse erro pode ocorrer quando o contato não atende aos critérios necessários para ser utilizado como um número de teste. 

2. Maximum number of test contacts

Descrição:

Indica que o limite máximo de contatos de teste permitidos já foi atingido.

Em caso de sucesso no cadastro do Test Contact, a API retornará o HTTP Status 200 (OK), indicando que a operação foi realizada com sucesso. 
 

Considerações

O endpoint deve ser utilizado exclusivamente para o propósito de gerenciamento dos contatos de teste suportados pelo recurso /phone-numbers/test-contacts.

A estrutura do resource deve respeitar o formato esperado pelo endpoint, especialmente os campos displayName e number.


 

Precisa de mais ajuda? Explore nossos conteúdos na Blip Academy ou Blip Community, assista a tutoriais no nosso canal do YouTube ou tire suas dúvidas em nosso canal de atendimento 😃

Artigos relacionados