Ir para o conteúdo

Como gerenciar números de telefone

Recupere números de telefone registrados por uma empresa na conta do WhatsApp Business.

Antes de começar

Você precisará do seguinte:

  • A identificação da conta do WhatsApp Business dos números de telefone da empresa que você quer recuperar (WabaId).
  • Um token de acesso para a plataforma.

Limitações

A API consegue recuperar apenas números de telefone que foram registrados. Não é permitido adicionar, atualizar ou excluir números de telefone.

Obter um único número de telefone

Para obter informações sobre um número de telefone, envie uma solicitação GET ao ponto de extremidade.

URI

URI: https://api.whatsapp.serpro.gov.br/waba/{wabaId}/v2/telefones/{id}
Método: GET

Em caso de sucesso, um objeto JSON é retornado com o nome, o número de telefone, o ID do telefone e as classificações de qualidade do número de telefone consultado. 

{
  "code_verification_status" : "VERIFIED",
  "display_phone_number" : "15555555555",
  "id" : "105954558954427",
  "quality_rating" : "GREEN",
  "verified_name" : "Support Number"
}

Obter todos os números de telefone

Para receber uma lista de todos os números de telefone associados a uma conta do WhatsApp Business, envie uma solicitação GET para o ponto de extremidade.

URI

URI: https://api.whatsapp.serpro.gov.br/waba/{wabaId}/v2/telefones
Método: GET

Em caso de sucesso, um objeto JSON é retornado com uma lista de todos os nomes, telefones, IDs de telefones e classificações de qualidade associadas a uma empresa. Os resultados são exibidos por data de conclusão do cadastro incorporado em ordem decrescente, com a integração mais recente listada primeiro. 

{
  "data": [
    {
      "verified_name": "Jasper's Market",
      "display_phone_number": "+1 631-555-5555",
      "id": "1906385232743451",
      "quality_rating": "GREEN"

    },
    {
      "verified_name": "Jasper's Ice Cream",
      "display_phone_number": "+1 631-555-5556",
      "id": "1913623884432103",
      "quality_rating": "NA"
    }
  ]
}

Ativar números de telefone

É preciso verificar o número de telefone que você quer usar para enviar mensagens aos clientes. Os números de telefone devem ser verificados por meio de um código enviado por SMS ou ligação de voz. O processo de verificação pode ser feito a partir das chamadas da Graph API especificadas a seguir.

URI

URI: https://api.whatsapp.serpro.gov.br/cliente/{fromPhoneNumberId}/v2/ativador/solicita-codigo
Método: POST

Na chamada, inclua o idioma e o método de verificação escolhido.

Parâmetros

Nome Descrição
code_method

string

 Obrigatório.

Método de verificação escolhido.

- SMS

- VOICE
language

string

 Obrigatório.

O código de dois caracteres do idioma. Por exemplo: "en_US".

Exemplo de solicitação: 

curl -X POST \
  'https://api.whatsapp.serpro.gov.br/cliente/{fromPhoneNumberId}/v2/ativador/solicita-codigo' \
  -H 'Authorization: Bearer ACCESS_TOKEN' \
  -F 'code_method=SMS' 
  -F 'language=en_US'

Depois da chamada de API, você receberá o código de verificação por meio do método selecionado. Para concluir o processo de verificação, inclua o código em uma solicitação POST.

URI

URI: https://api.whatsapp.serpro.gov.br/cliente/{fromPhoneNumberId}/v2/ativador/verifica-codigo
Método: POST

Parâmetros

Nome Descrição
code

string numérica

 Obrigatório.

O código recebido depois de fazer a chamada.

Exemplo de solicitação:

curl -X POST \
  'https://api.whatsapp.serpro.gov.br/cliente/{fromPhoneNumberId}/v2/ativador/verifica-codigo' \
  -H 'Authorization: Bearer ACCESS_TOKEN' \
  -F 'code=000000'

A resposta bem-sucedida é semelhante a esta:

{
  "success": true
}

Status que podem ocorrer na ativação de um telefone

  • 'PENDING'
  • 'DELETED'
  • 'MIGRATED'
  • 'BANNED'
  • 'RESTRICTED'
  • 'RATE_LIMITED'
  • 'FLAGGED'
  • 'CONNECTED'
  • 'DISCONNECTED'
  • 'UNKNOWN'
  • 'UNVERIFIED'

Recuperar WabaId

Recupere o WabaId e o nome informados por uma empresa na conta do WhatsApp Business enviando uma solicitação GET para o ponto de extremidade.

URI

URI: https://api.whatsapp.serpro.gov.br/waba/{wabaId}
Método: GET

Em caso de sucesso, um objeto JSON é retornado com os dados do WabaId consultado. 

{
    "id": "105954558954427",
    "name": "Support Number"
}