Recuperar números de telefone

Recupere números de telefone registrados por uma empresa na conta do WhatsApp Business com a API de Gerenciamento 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.
• Um token de acesso de usuário do sistema vinculado à conta do WhatsApp Business.
• A permissão whatsapp_business_management.

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 usando a API.

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 de conta do WhatsApp Business > números de telefone.

Além disso, os números de telefone podem ser classificados em ordem crescente ou decrescente de acordo com o last_onboarded_time, que é baseado em quando o usuário concluiu a integração do cadastro incorporado. Se não for especificada, a ordem-padrão é decrescente.

Exemplo de solicitação

curl -X GET "https://graph.facebook.com/v19.0/{whatsapp-business-account-id}/phone_numbers
      ?access_token={system-user-access-token}"

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

Exemplo de solicitação

curl -X GET "https://graph.facebook.com/v19.0/{whatsapp-business-account-id}/phone_numbers
      ?access_token={system-user-access-token}]&sort=['last_onboarded_time_ascending']"

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 em ordem crescente com base em quando o usuário concluiu o cadastro incorporado, com a integração mais recente listada por último.

{
  "data": [
   {
      "verified_name": "Jasper's Ice Cream",
      "display_phone_number": "+1 631-555-5556",
      "id": "1913623884432103",
      "quality_rating": "NA"
    },
    {
      "verified_name": "Jasper's Market",
      "display_phone_number": "+1 631-555-5555",
      "id": "1906385232743451",
      "quality_rating": "GREEN"     
    }   
  ]
}

Filtrar números de telefone

Consulte e filtre números de telefone com base em account_mode. No momento, essa opção de filtragem está sendo testada no modo beta. Nem todos os desenvolvedores têm acesso ao recurso.

Parâmetros

Exemplo de solicitação

curl -i -X GET "https://graph.facebook.com/v19.0/{whatsapp-business-account-ID}/phone_numbers?filtering=[{"field":"account_mode","operator":"EQUAL","value":"SANDBOX"}]&access_token=access-token"

Exemplo de resposta

{
  "data": [
    {
      "id": "1972385232742141",    
      "display_phone_number": "+1 631-555-1111",
      "verified_name": "John’s Cake Shop",
      "quality_rating": "UNKNOWN",
    }
  ],
  "paging": {
	"cursors": {
		"before": "abcdefghij",
		"after": "klmnopqr"
	}
   }
}

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 de número de telefone do WhatsApp Business:

Sintaxe da solicitação

GET https://graph.facebook.com/<API_VERSION>/<PHONE_NUMBER_ID>

Exemplo de solicitação

curl \
'https://graph.facebook.com/v15.0/105954558954427/' \
-H 'Authorization: Bearer EAAFl...'

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 status do nome de exibição (beta)

Inclua fields=name_status como um parâmetro da string de consulta para obter o status do nome de exibição associado a um número de telefone específico. No momento, esse campo está na versão beta e não está disponível para todos os desenvolvedores.

Exemplo de solicitação

curl \
'https://graph.facebook.com/v15.0/105954558954427?fields=name_status' \
-H 'Authorization: Bearer EAAFl...'

Exemplo de resposta

{
  "id" : "105954558954427",
  "name_status" : "AVAILABLE_WITHOUT_REVIEW"
}

O valor name_status pode ser um dos seguintes:

• APPROVED – o nome foi aprovado. Você já pode baixar o certificado.
• AVAILABLE_WITHOUT_REVIEW – o certificado do telefone está disponível, e o nome de exibição está pronto para ser usado sem análise.
• DECLINED – o nome não foi aprovado. Não é possível baixar o certificado.
• EXPIRED – o certificado expirou e não é mais possível baixá-lo.
• PENDING_REVIEW – a solicitação de nome está em análise. Não é possível baixar o certificado.
• NONE – não há certificados disponíveis.

Os certificados têm validade de sete dias.

Saiba mais

Para ver uma lista de todos os valores possíveis para cada campo, consulte a referência da Graph API sobre o campo de número de telefone.