Números de telefone pré-verificados

Este documento explica como oferecer aos clientes finais números de telefone comercial pré-verificados no novo fluxo de Cadastro Incorporado. Esses números de telefone comercial pré-verificados são aqueles que você já verificou. Ou seja, os clientes finais não precisam entrar em contato com você para obter uma senha descartável.

Eles são representados por objetos WhatsApp Business Pre-Verified Phone Number, que são temporários. Se um cliente final selecionar um desses números e concluir o novo fluxo de Cadastro Incorporado, o objeto temporário será substituído por um objeto WhatsApp Business Phone Number, e você precisará obter o ID do novo objeto para registrar o número.

Requisitos

Sua empresa deve ser um parceiro de soluções aprovado.
O usuário do app deve ser um administrador da empresa na conta comercial à qual os números de telefone comercial pré-verificados serão adicionados.
Um usuário ou token de acesso do usuário do sistema.
A permissão business_management.
Os números de telefone comercial devem ser válidos.

Limitações

Disponível somente com o novo fluxo de cadastro incorporado. Leia o documento Incorporar o Fluxo de Cadastro com tokens de acesso do usuário do sistema para aprender como habilitar o novo fluxo.
Você é responsável por acompanhar quem reivindicou um número de telefone comercial pré-verificado.
Se um número de telefone comercial pré-verificado não for reivindicado por um cliente final no fluxo de Cadastro Incorporado dentro de 90 dias após a verificação, o estado dele será revertido para não verificado. Além disso, para restaurar o estado verificado por mais 90 dias, será preciso fazer uma nova verificação do número.
Os números de telefone comercial pré-verificados que não foram reivindicados não poderão ser verificados novamente até 45 dias antes da data de reversão programada para o status não verificado. O tempo é indicado no campo verification_expiry_time.
Se você adicionar um número de telefone ao seu conjunto de números de telefone comercial pré-verificados (Etapa 1), mas não o verificar dentro de 90 dias (Etapa 3), ele será removido do conjunto e precisará ser adicionado novamente.

Como criar números pré-verificados

Siga estas etapas para criar um número de telefone comercial pré-verificado, exibi-lo no Cadastro Incorporado e fazer o registro dele após a reivindicação de um cliente final.

Etapa 1: criar um número de telefone comercial pré-verificado

Use o ponto de extremidade Business Account > Add Phone Numbers para criar um número de telefone comercial pré-verificado para sua empresa. Isso o adicionará ao seu conjunto de números.

Sintaxe da solicitação

POST /<BUSINESS_ACCOUNT_ID>/add_phone_numbers
  ?phone_number=<PHONE_NUMBER>

Resposta

Em caso de sucesso, a API retornará um ID de Número de telefone pré-verificado do WhatsApp Business. Copie esse valor para usar na próxima solicitação.

{
  "id": "<WHATSAPP_BUSINESS_PRE_VERIFIED_PHONE_NUMBER_ID>"
}

Exemplo de solicitação

curl -X POST 'https://graph.facebook.com/v19.0/506914307656634/add_phone_numbers?phone_number=15550783881' \
-H 'Authorization: Bearer EAAJB...'

Exemplo de resposta

{
  "id": "106540352242922"
}

Consulte a referência do ponto de extremidade Business Account > Add Phone Numbers para ver os formatos de números de telefone e parâmetros de consulta compatíveis.

Etapa 2: solicitar um código de verificação

Use o ponto de extremidade WhatsApp Business Pre-Verified Phone Number > Request Code para solicitar uma senha descartável via SMS ou mensagem de voz para o novo número de telefone comercial pré-verificado.

Sintaxe da solicitação

POST /<WHATSAPP_BUSINESS_PRE_VERIFIED_PHONE_NUMBER_ID>/request_code
  ?code_method=<CODE_METHOD>
  &language=<LANGUAGE>

Resposta

Em caso de sucesso, a API retornará true.

{
  "success": <SUCCESS>
}

Além disso, enviaremos um SMS ou uma mensagem de voz contendo uma senha descartável para o número de telefone. Copie a senha descartável para usar na próxima solicitação.

Sintaxe de SMS de senha descartável

WhatsApp code <CODE>

Sintaxe de mensagem de voz de senha descartável

Repetido três vezes.

Verification code is <CODE>

Exemplo de solicitação

curl -X POST 'https://graph.facebook.com/v19.0/106540352242922/request_code?code_method=SMS&language=en_US' \
-H 'Authorization: Bearer EAAJB...'

Exemplo de resposta

{
  "success": true
}

Exemplo de mensagem de SMS de senha descartável

WhatsApp code 123-456

Exemplo de mensagem de voz de senha descartável

Repetido três vezes.

Verification code is 123456

Consulte a referência do ponto de extremidade Número de telefone pré-verificado do WhatsApp Business > Solicitar código para ver os métodos de código, idiomas e parâmetros de consulta compatíveis.

Etapa 3: verificar o número

Use o ponto de extremidade Número de telefone pré-verificado do WhatsApp Business > Verificar código para verificar o número de telefone comercial usando sua senha descartável.

Sintaxe da solicitação

POST /<WHATSAPP_BUSINESS_PRE_VERIFIED_PHONE_NUMBER_ID>/verify_code
  ?code=<CODE>

Resposta

Caso seja bem-sucedida, a API retornará true, e o número de telefone comercial terá o code_verification_status definido como VERIFIED por 90 dias.

{
  "success": <SUCCESS>
}

Exemplo de solicitação

curl -X POST 'https://graph.facebook.com/v19.0/106540352242922/verify_code?code=123456' \
-H 'Authorization: Bearer EAAJB...'

Exemplo de resposta

{
  "success": true
}

Consulte a referência do ponto de extremidade Número de telefone pré-verificado do WhatsApp Business > Verificar código para ver os parâmetros de consulta compatíveis.

Assim que você tiver um número de telefone comercial pré-verificado com um status verificado (ou um conjunto de números), exiba-o no novo fluxo de Cadastro Incorporado.

Como exibir números pré-verificados no Cadastro Incorporado

Você pode exibir números de telefone comercial pré-verificados no novo fluxo de Cadastro Incorporado por meio de dados de formulário pré-preenchidos. Para fazer isso, adicione um objeto preVerifiedPhone com uma propriedade ids ao objeto setup e atribua os IDs dos números de telefone comercial pré-verificados como uma matriz de strings à propriedade ids:

{
  scope: '<SCOPE>',
  extras: {
    feature: '<FEATURE>',
    setup: {
      preVerifiedPhone: {
        ids: [<IDS>]
      }
    }
  }
}

Por exemplo:

{
  scope: 'business_management,whatsapp_business_management',
  extras: {
    feature: 'whatsapp_embedded_signup',
    version: 2,
    setup: {
	business: {
	  name: 'Acme Inc.',
	  email: 'johndoe@acme.com',
	  phone: {
	    code: 1,
	    number: '6505551234'
        },
	  website: 'https://www.acme.com',
        address: {
          streetAddress1: '1 Acme Way',
          city: 'Acme Town',
          state: 'CA',
          zipPostal: '94000',
          country: 'US'
        },
        timezone: 'UTC-08:00'
      },
      phone: {
        displayName: 'Acme Inc.',
        category: 'ENTERTAIN',
        description: 'Gears and widgets'
      },
      preVerifiedPhone: {
        ids: ['106540352242922','105954558954427']
      }
    }
  }
}

Se um número de telefone comercial pré-verificado com status VERIFIED não for reivindicado dentro de 90 dias após a verificação, o status dele será definido como UNVERIFIED, mas ele ainda aparecerá no novo fluxo de Cadastro Incorporado. Caso um cliente final tente reivindicar um número não verificado, ele precisará concluir a verificação por conta própria, ou seja, deverá solicitar a você uma senha descartável.

Para evitar essa experiência desagradável para o usuário, recomendamos que você monitore quando verificou um número e o verifique novamente antes que ele volte a ter um estado não verificado.

Se você não tiver certeza de quando verificou pela última vez determinado número de telefone comercial pré-verificado, consulte o ponto de extremidade WhatsApp Business Pre-Verified Phone Number e consulte os campos code_verification_time e verification_expiry_time, que indicam a data da verificação mais recente e o prazo de validade.

Como determinar se um número foi reivindicado por meio do Cadastro Incorporado

Consulte Como obter IDs de números de telefone reivindicados.

Como obter IDs de números de telefone reivindicados

Execute uma solicitação GET no ponto de extremidade WhatsApp Business Account > Phone Numbers, que retorna todos os números de telefone do WhatsApp Business em uma conta do WhatsApp Business.

Analise a propriedade display_phone_number em cada objeto retornado no conjunto de resultados. Se um objeto tiver o número de telefone de exibição (por exemplo, 16505551234) como seu valor display_phone_number, ele foi reivindicado. Copie o valor da propriedade id do objeto, uma vez que essa é o ID do novo objeto Número de telefone do WhatsApp Business que agora representa esse número (o ID antigo não funcionará mais).

Alternativamente, você pode usar o mesmo ponto de extremidade com a expansão field para solicitar o campo display_phone_number e especificar o número de telefone de exibição. Por exemplo:

GET /102290129340398/phone_numbers?display_phone_number=16505551234

Se isso retornar um objeto "WhatsApp Business Phone Number" com esse número de telefone de exibição, o número foi reivindicado, e você deve copiar o id do objeto.

Obter números de telefone comercial pré-verificados

Use o ponto de extremidade Business Account > Preverified Numbers para obter uma lista de todos os objetos WhatsApp Business Pre-Verified Phone Number (independentemente do estado de verificação) no conjunto de números de telefone comercial pré-verificados da sua conta:

GET /<BUSINESS_ACCOUNT_ID>/preverified_numbers

Os resultados são classificados automaticamente por data de criação. Você também pode utilizar a expansão do campo para solicitar o campo code_verification_status, assim, a API retornará apenas números de telefone comercial pré-verificados com o estado de verificação indicado:

GET /<BUSINESS_ACCOUNT_ID>/preverified_numbers?code_verification_status=VERIFIED

Como compartilhar e cancelar o compartilhamento de números pré-verificados

Envie uma solicitação POST ao ponto de extremidade Business > Share Preverified Numbers para compartilhar números de telefone comercial pré-verificados com parceiros de negócios. Se quiser cancelar o compartilhamento, envie uma solicitação DELETE para o mesmo ponto de extremidade.

Os números de telefone comercial pré-verificados que forem compartilhados poderão ser exibidos por parceiros de negócios no fluxo de Cadastro Incorporado.

Caso esteja compartilhando números com vários parceiros de negócios, recomendamos que você os oriente a obter uma lista dos números pré-verificados que foram compartilhados antes de exibi-los no Cadastro Incorporado. Isso reduz a probabilidade de um parceiro tentar exibir um número que já foi reivindicado. Os números reivindicados não são exibidos no fluxo, mas o parceiro pode não saber disso e se perguntar por que um determinado número não está aparecendo.

Sintaxe da solicitação de compartilhamento

POST /<BUSINESS_ID>/share_preverified_numbers
  ?partner_business_id=<PARTNER_BUSINESS_ID>
  &preverified_id=<PREVERIFIED_ID>

Sintaxe da solicitação de cancelamento do compartilhamento

DELETE /<BUSINESS_ID>/share_preverified_numbers
  ?partner_business_id=<PARTNER_BUSINESS_ID>
  &preverified_id=<PREVERIFIED_ID>

Resposta

Se for bem-sucedida, a API retornará "true". Em caso de compartilhamento, notifique seu parceiro de negócios sobre o número pré-verificado que foi compartilhado e forneça o ID relacionado. Em caso de cancelamento do compartilhamento, o número não aparecerá mais na implementação do Cadastro Incorporado do parceiro.

{
  "success": <SUCCESS>
}

Exemplo de solicitação de compartilhamento

curl -X POST 'https://graph.facebook.com/v17.0/share_preverified_numbers?partner_business_id=506914307656634&preverified_id=1706193509821738' \
-H 'Authorization: Bearer EAAH0...'

Exemplo de solicitação de cancelamento do compartilhamento

curl -X DELETE 'https://graph.facebook.com/v17.0/share_preverified_numbers?partner_business_id=506914307656634&preverified_id=1706193509821738' \
-H 'Authorization: Bearer EAAH0...'

Exemplo de resposta

{
  "success": true
}

Como registrar números pré-verificados de modo programático

É possível ignorar a seleção de número de telefone no Cadastro Incorporado e registrar de forma programática números de telefone comercial pré-verificados em clientes finais integrados no WhatsApp Business. Para isso, siga as etapas descritas no documento Números de telefone pré-verificados, mas use um ID de número de telefone comercial pré-verificado na Etapa 1 e, depois, pule para a Etapa 4.

Sintaxe da solicitação

Use esta solicitação para criar um número de telefone comercial em uma conta do WhatsApp Business com o ID de um número de telefone comercial pré-verificado. Isso substitui a Etapa 1.

POST /<WHATSAPP_BUSINESS_ACCOUNT_ID>/phone_numbers

Corpo da publicação

{
  "preverified_id": "<PREVERIFIED_ID>",
  "country_dial_code": "<COUNTRY_DIAL_CODE>",
  "display_phone_number": "<DISPLAY_PHONE_NUMBER>",
  "verified_name": "<VERIFIED_NAME>"
}

Propriedades

Espaço reservado Descrição Valor de exemplo

Espaço reservado	Descrição	Valor de exemplo
`<PREVERIFIED_ID>` String	Obrigatório. O ID do número de telefone comercial pré-verificado.	`6635066806614622`
`<COUNTRY_DIAL_CODE>` String	Obrigatório. O código de discagem do país do número de telefone comercial pré-verificado.	`1`
`<DISPLAY_PHONE_NUMBER>` String	Obrigatório. O número de exibição do telefone comercial pré-verificado.	`5550783881`
`<VERIFIED_NAME>` String	Obrigatório. O nome de exibição do número de telefone comercial pré-verificado.	`Lucky Shrub`

<PREVERIFIED_ID>

String

Obrigatório.

O ID do número de telefone comercial pré-verificado.

6635066806614622

<COUNTRY_DIAL_CODE>

String

Obrigatório.

O código de discagem do país do número de telefone comercial pré-verificado.

1

<DISPLAY_PHONE_NUMBER>

String

Obrigatório.

O número de exibição do telefone comercial pré-verificado.

5550783881

<VERIFIED_NAME>

String

Obrigatório.

O nome de exibição do número de telefone comercial pré-verificado.

Lucky Shrub

Sintaxe da resposta

Se for bem-sucedida, a API responderá com o ID de um número de telefone do WhatsApp Business. Use esse ID para registrar o número (Etapa 4 descrita no documento Registering Phone Numbers).

{
  "id": "<ID>"
}

Propriedades da resposta

Espaço reservado Descrição Valor de exemplo

Espaço reservado	Descrição	Valor de exemplo
`<ID>`	O ID de um número de telefone do WhatsApp Business. Este objeto substituiu o objeto WhatsApp Business Pre-Verified Phone Number.	`108692048990658`

<ID>

O ID de um número de telefone do WhatsApp Business.

Este objeto substituiu o objeto WhatsApp Business Pre-Verified Phone Number.

108692048990658

Exemplo de solicitação

curl 'https://graph.facebook.com/v19.0/506914307656634/phone_numbers' \
-H 'Content-Type: text/plain' \
-H 'Authorization: Bearer EAAH7...' \
-d '
{
  "preverified_id": "6635066806614622",
  "country_dial_code": "1",
  "display_phone_number": "5550783881",
  "verified_name": "Lucky Shrub"
}'

Exemplo de resposta

{
  "id": "108692048990658"
}