# REQUEST_CONTACT_INFO — pedir telefone ao contato (Meta oficial e Gupshup) | Campo | Valor | | :---- | :---- | | Status | Ciclo completo confirmado ao vivo (Meta e Gupshup): criar template com botão → aprovado pela Meta/Gupshup → enviar mensagem de template com o botão. Suporte no front-end (criação de template) implementado. Reveal de telefone entregue ao cliente final via `NEW_MESSAGE` (mecanismo já existente, sem evento novo) — formato do webhook de resposta (`origin: contact_request`) confirmado na documentação oficial dos **dois** parceiros, Meta e Gupshup; só falta validar com um caso real de produção | | Escopo de parceiro | **Meta Cloud API** e **Gupshup** (mesmo `ProcessMessageInterface` compartilhado usado por Flow/Location/Button — ver [Padrão: orquestrador multi-parceiro](../architecture/ARCHITECTURE.md#padrão-orquestrador-multi-parceiro-coreomnimetausecase)). Evolution API não suportado | | ADR | Nenhum dedicado | ## Objetivo Pedir o número de telefone de um contato conhecido **só pelo `bsuid`** (WhatsApp username, sem opt-in de número) — cenário criado pelo rollout de "WhatsApp usernames" da Meta (a partir de jun/2026), em que o usuário pode esconder o telefone real e a Meta só entrega o `bsuid` no webhook. O compartilhamento é sempre uma ação voluntária do usuário ao tocar num botão nativo da Meta — **não exige opt-in prévio**. ## Escopo | Incluído | Excluído / futuro | | :------- | :----------------- | | Enviar `interactive.request_contact_info` dentro da janela de sessão de 24h — Meta e Gupshup | — | | Criar template com botão `REQUEST_CONTACT_INFO` via API (`POST /templates`) e pelo front-end, e enviar mensagem de template usando esse botão | — | | Envio para contato identificado só por `bsuid` (via `userId` — reaproveita a resolução de identificação já existente, sem alteração) | — | | Associar o `wa_id` revelado ao contato existente quando a resposta chega como mensagem `contacts` com `origin: contact_request` | Validação com um caso real de cliente aceitando o compartilhamento | | — | Tela no front-end para disparar o envio da mensagem interativa livre | **Decisão de design (não criar evento de webhook novo):** o reveal de telefone não tem um evento outbound dedicado — ele é, na prática, uma mensagem inbound como qualquer outra, então quem já assina `NEW_MESSAGE` já recebe automaticamente, sem precisar assinar nada a mais. Ver ["Entrega ao cliente final"](#entrega-ao-cliente-final--já-cai-no-new_message) abaixo. ## Estado atual (evidência no código) | Tema | Situação | Arquivo / evidência | | :--- | :------- | :------------------ | | Enum de conteúdo | `MessageContentsEnum::REQUEST_CONTACT_INFO = 'request_contact_info'` | `api/src/Core/Domain/Enum/Meta/Messages/MessageContentsEnum.php` | | Validação de envio | `body` obrigatório, string, max 1024 | `api/src/Core/Domain/Validation/Message/RequestContactInfoValidation.php` | | Montagem do payload (Meta e Gupshup) | `{"type":"interactive","interactive":{"type":"request_contact_info","body":{"text":...},"action":{"name":"request_contact_info"}}}` — idêntico nos dois parceiros; reaproveitado sem alteração pela Gupshup, mesmo padrão do Flow | `api/src/Core/UseCase/Message/ProcessRequestContactInfoUseCase.php` | | Registro no strategy map de envio | Meta e Gupshup, cada um no seu `resolveMessageContentStrategy` | `Core\UseCase\Message\SendWhatsappMessageUseCase`, `Core\Gupshup\UseCase\GupshupSendWhatsappMessageUseCase` | | API REST | `POST /api/v1/channels/whatsapp/messages`, `contents[].type = "request_contact_info"` — exemplo no Swagger (`@OA\Examples` `request_contact_info`) | `api/app/Http/Controllers/OmniBusinessController.php` | | Envio para contato só com bsuid | Já suportado sem alteração — reaproveita `resolveIdentification`/`buildIdentificationAttempts` existente (prioriza `wa_id`+`bsuid`, depois `bsuid`, depois `wa_id`) | ambos `SendWhatsappMessageUseCase` | | Troca de bsuid / número (mecanismo separado desta feature) | A Meta entrega a troca no campo `messages` como mensagem de sistema (`type: system`, `system.type` = `user_changed_number` ou `user_changed_user_id`; sem array `contacts`; `from` = número antigo, `system.wa_id` = número novo, `system.user_id`/`previous_user_id` = bsuid novo/anterior). O contato existente é atualizado no lugar (mesmo id → mesmo `visitor.userId` pro cliente), nunca recriado; a troca é aplicada em todos os números da mesma `whatsapp_account` (contato é por número da empresa, BSUID é por portfólio, e a Meta não documenta se manda a mensagem de sistema uma vez por número — se mandar, as seguintes são no-op); `user_changed_user_id` sem `wa_id` significa número novo oculto (o BSUID só é regenerado na troca de número), então o `wa_id` antigo é limpo para o envio não ir ao número antigo (`to` tem precedência sobre o BSUID na Meta) — o contato passa a ser só-bsuid e o `NEW_MESSAGE` vai com `from` vazio; se o identificador novo já pertence a outro contato, só loga. Bookkeeping interno: a mensagem não é persistida nem gera `NEW_MESSAGE`. O campo `user_id_update` não existe segundo a doc da Meta (corrigida em 11/08/2026) — o processador legado foi mantido usando a mesma regra | `MessageProcessing::applyContactIdentityChange()`, `Core\UseCase\Contact\UpdateContactUserIdUseCase`, `api/src/Core/Application/Webhook/Contacts/UserIdUpdateProcessing.php` (legado) | | Captura do reveal como mensagem `contacts` | Quando chega uma mensagem inbound `type=contacts` pra um contato que ainda não tinha `wa_id`, só grava o telefone (`contacts[0].phones[0].phone`) como `wa_id` do contato se `contacts[0].origin === 'contact_request'` (confirmado na doc oficial da Meta — ver seção "Formato confirmado" abaixo); se `origin` for `other` (contato compartilhado manualmente, de terceiro), ignora — a mensagem em si sempre segue o fluxo normal (persistida, `NEW_MESSAGE` disparado) | `MessageProcessing::captureRevealedPhoneNumber()` (`api/src/Core/Application/Webhook/Messages/MessageProcessing.php`) | | Entrega ao cliente final | **Sem código novo** — `MessageWebhookTriggerUseCase::processContents()` já expõe mensagens `type=contacts` (`contacts: $newMessage->content`, com o vCard completo, telefone incluso) pra qualquer assinante de `NEW_MESSAGE`; o payload já usa `phone.phoneNumber` (não um id interno) e não tem `clientId` | `api/src/Core/UseCase/Webhook/MessageWebhookTriggerUseCase.php` | | Criação de template com botão (backend) | Sem código novo — `CreateTemplateRequest` não tem whitelist de `buttons.*.type` (só valida `components[].type`) e o caminho até a Graph API/Gupshup Partner API é passthrough puro (`components` do request repassado como está); nenhuma alteração foi necessária | `api/app/Http/Requests/CreateTemplateRequest.php`, `Core\UseCase\Template\CreateTemplateUseCase` (Meta), `Core\Gupshup\UseCase\CreateTemplateUseCase` | | Criação de template com botão (front-end) | Novo tipo de botão "Pedir telefone ao contato" no dropdown, sem campo de texto editável (rótulo é definido pela Meta/Gupshup); limite de 1 por template; builder monta `{"type": "REQUEST_CONTACT_INFO"}` sem `text` | `front/src/app/main/apps/template/components/ButtonsConfiguration.tsx`, `front/src/app/util/templateComponentsBuilder.ts` (`buildButtonsComponent`) | ## Envio (exemplo) ```json { "from": "5511999999999", "userId": "3a2b1c0d-4444-4e55-8f66-777788889999", "contents": [{ "type": "request_contact_info", "body": "Para continuar seu atendimento, precisamos do seu número de telefone." }] } ``` `to` funciona normalmente quando o `wa_id` já é conhecido; para um contato só-bsuid, use `userId` (id local do OmniMeta) — mesma convenção já usada em Flow/Groups para endereçar um recurso resolvido internamente em vez de expor o dado bruto do parceiro. ## Criação de template com botão (exemplo) ```json { "whatsappAccountId": "", "name": "meu_template", "category": "UTILITY", "language": "pt_BR", "components": [ { "type": "BODY", "text": "Para continuar seu atendimento, precisamos confirmar seu número de telefone." }, { "type": "BUTTONS", "buttons": [ { "type": "REQUEST_CONTACT_INFO" } ] } ] } ``` **Atenção — `category` vai em maiúsculas** (`UTILITY`, não `utility`): a regra de validação de `CreateTemplateRequest` faz `strtoupper()` na whitelist mas não no valor recebido, então só aceita o valor já em caixa alta — divergência não documentada no Swagger, descoberta no teste ao vivo. O botão não precisa (nem aceita) `text` customizado — tanto a Meta quanto a Gupshup preenchem/tratam o rótulo automaticamente (a Meta ecoou de volta `"text": "Share Contact Info"` no template criado). ## Entrega ao cliente final — já cai no `NEW_MESSAGE` O reveal de telefone não ganhou um evento de webhook dedicado de propósito: ele é, na prática, uma mensagem inbound (o WhatsApp entrega como uma mensagem `type=contacts`) — então tratá-lo como um evento à parte obrigaria todo cliente que já assina `NEW_MESSAGE` a assinar mais um evento pra receber a mesma informação. Em vez disso, quando essa mensagem chega: 1. `MessageProcessing::processMessage()` persiste a mensagem normalmente (mesmo fluxo de qualquer mensagem `contacts` — ex.: alguém compartilhando um contato manualmente no chat). 2. Se o contato ainda não tinha `wa_id` (só `bsuid`) **e** a entrada correspondente em `message.contacts[0]` tem `origin === 'contact_request'`, `captureRevealedPhoneNumber()` extrai o telefone (`contacts[0].phones[0].phone`) e grava como `wa_id` do contato. Se `origin` for `other`, ignora — é um contato de terceiro compartilhado manualmente, não uma revelação do próprio número (ver "Formato confirmado" abaixo). 3. O `NEW_MESSAGE` dispara do jeito de sempre (`MessageWebhookTriggerUseCase`), com o conteúdo completo em `message.contents[0].contacts` — o cliente final vê o telefone dentro do conteúdo da própria mensagem, sem precisar de um campo/evento especial. Esse payload de `NEW_MESSAGE` já segue a convenção correta por conta própria (nada precisou ser ajustado pra isso): usa `phone.phoneNumber` real como `message.to`, nunca um `clientId` ou id interno. ### Formato confirmado na documentação oficial da Meta Página `developers.facebook.com/documentation/business-messaging/whatsapp/business-scoped-user-ids/` ("Como solicitar o número de telefone dos usuários"), extraído diretamente do HTML da página (2026-09-14) — trecho verbatim traduzido: > Se um usuário tocar nesse botão, o número de telefone do WhatsApp dele será compartilhado no > tópico da mensagem, e um webhook de contatos será disparado contendo o número de telefone do > usuário. Se o usuário do WhatsApp compartilhar um contato usando o recurso de compartilhamento de > contatos no app do WhatsApp, o webhook também incluirá o vCard do contato. Schema exato do webhook (campos novos marcados `` na doc original): ```json { "messages": [ { "id": "", "timestamp": "", "type": "contacts", "from_user_id": "", "contacts": [ { "vcard": "", "origin": "", "phones": [ { "phone": "", "wa_id": "", "type": "" } ] } ] } ], "field": "messages" } ``` - `from_user_id`: novo campo, definido como o BSUID do usuário. - `origin`: novo campo, indica como as informações de contato foram compartilhadas — `contact_request` (usuário tocou no botão `REQUEST_CONTACT_INFO`) ou `other` (usuário compartilhou um contato manualmente, não pelo botão). - `vcard`: presente (com os dados do contato de fato compartilhado) quando `origin` é `other`; **omitido** quando `origin` é `contact_request`. Isso confirma que `captureRevealedPhoneNumber()` está correto ao checar `origin === 'contact_request'` antes de gravar o telefone — sem esse filtro, um contato bsuid-only que compartilhasse manualmente o cartão de outra pessoa (`origin: other`) teria o número de terceiro gravado como se fosse o próprio. **Validado em 2026-09-14** (não é um teste ao vivo real, mas exercita o pipeline real): reproduzido esse payload exato via `ProcessWebhookUseCase` (mesma classe que o `WebhookController` chama) contra o backend local, nos dois cenários — Bruno collection em `request-collections/OmniMeta/Bruno/Webhook/` (repo irmão de `omnimeta`, pasta `Produtos/request-collections`), requests `Facebook partner - Contact Info Shared (contact_request)` e `Facebook partner - Contact Shared Manually (origin other)`: com `origin: contact_request` o Contact ficou com `wa_id` preenchido corretamente; com `origin: other` o `wa_id` ficou vazio, como esperado (guard funcionou). Repeti o mesmo teste em 2026-09-14 passando o payload pelo caminho da Gupshup (`NormalizeIncomingWebhookPayloadUseCase` → `ProcessWebhookUseCase`, exatamente o que `GupshupWebhookController::index()` chama) — resultado idêntico, contato criado na conta Gupshup de teste com `wa_id` preenchido corretamente. Não é um caminho duplicado: a Gupshup só entra no `ProcessWebhookUseCase`/`MessageProcessing` compartilhado se o normalizador reconhecer o payload como envelope Meta-like (`object`+`entry`+`changes`) — que é como a Gupshup já envia `messages`/`contacts` normais (evidência: bsuid já era capturado assim antes desta feature). Se a Gupshup tratar esse evento específico no formato proprietário dela (como faz com `message-event`/`billing-event`), o normalizador não tem tradução pra isso hoje e o payload cairia como `status: "ignored"` — precisaria de um branch novo, igual aos já existentes. **Confirmado na documentação oficial da Gupshup em 2026-09-14** — `partner-docs.gupshup.io/docs/bsuid`, seção "Request Contact Info BSUID Webhook Event" (extraído do HTML cru da página, não resumo de IA). A Gupshup documenta o **mesmo mecanismo, com os mesmos nomes de campo**, byte a byte igual à Meta: > When a user taps the REQUEST_CONTACT_INFO button (or shares a contact directly in chat), a > contacts webhook is triggered with message type: contacts. | Campo | Local | Descrição | | :--- | :--- | :--- | | `from_user_id` | `messages[]` | O BSUID de quem enviou. | | `origin` | `messages[].contacts[]` | Como o contato foi compartilhado. | | `vcard` | `messages[].contacts[]` | Presente só quando `origin` é `other`. | | Valor de `origin` | Significado | | :--- | :--- | | `contact_request` | Usuário tocou no botão `REQUEST_CONTACT_INFO`. `vcard` é omitido. | | `other` | Usuário compartilhou um contato diretamente do app do WhatsApp. `vcard` é incluído. | Exemplo real da doc da Gupshup (dados de teste deles, não fabricado por mim): ```json { "entry": [{ "changes": [{ "field": "messages", "value": { "contacts": [{ "profile": {"name": "Avadhoot Yadav"}, "user_id": "IN.3724117084395812", "wa_id": "917506080480" }], "messages": [{ "contacts": [{ "name": {"first_name": "Avadhoot Yadav", "formatted_name": "Avadhoot Yadav"}, "origin": "contact_request", "phones": [{ "phone": "+917506080480", "type": "CELL", "wa_id": "917506080480" }] }], "from": "917506080480", "from_user_id": "IN.3724117084395812", "id": "wamid...", "type": "contacts" }], "messaging_product": "whatsapp", "metadata": { "display_phone_number": "919355094343", "phone_number_id": "1314981035021901" } } }], "id": "954612427665223" }], "gs_app_id": "...", "object": "whatsapp_business_account" } ``` **Nota honesta:** o exemplo JSON publicado pela própria Gupshup mostra `vcard` presente mesmo com `origin: "contact_request"` — o que contradiz a tabela de campos logo acima ("vcard presente só quando origin é other"). Provavelmente um exemplo desatualizado/reaproveitado na doc deles, não um comportamento real diferente — a especificação em prosa é explícita e bate com a Meta. De qualquer forma, isso não afeta `captureRevealedPhoneNumber()`: ele só olha `origin` e `phones[0].phone`, nunca lê `vcard`. Isso fecha a lacuna que eu tinha deixado em aberto: **o gatilho (`type=contacts` + `origin`) é confirmado nos dois parceiros, Meta e Gupshup, com o mesmo formato**. O que ainda não é possível confirmar sem um caso real é o comportamento ao vivo em produção (vs. o exemplo de teste documentado). ## Testado ao vivo (2026-09-11) - Envio via Meta oficial (`551131327075` → `5511935856707`, endereçado por `to`): aceito pela Graph API, `wamid` real retornado e persistido. - Envio via Gupshup (`551131926788` → `5511935856707`, endereçado por `to`): aceito pela API da Gupshup, id de mensagem real retornado e persistido. - Envio via Gupshup endereçado só por `userId` (contato interno com `bsuid` conhecido — mesmo caminho que um contato bsuid-only usaria): aceito normalmente, confirma que a resolução de identificação já existente cobre o cenário sem alteração. - Criação de template com botão `REQUEST_CONTACT_INFO` via Meta (`whatsappAccountId` `e185f425-c8fc-41f9-93c0-360a82e3ea25`): aceito pela Graph API, `template_id` real `1772080203829199`, status `PENDING`, botão retornou com `text: "Share Contact Info"` preenchido pela própria Meta — confirma que o tipo de botão é reconhecido de verdade, não só aceito como JSON arbitrário. - Criação de template com botão `REQUEST_CONTACT_INFO` via Gupshup (`whatsappAccountId` `0e56aae5-b770-4530-9e4f-fd4008dcc9d7`): aceito pela Partner API, `template_id` real `dc5048ff-9948-417c-9ad4-0a50c439a941`, status `PENDING`. - Os dois templates de teste foram **aprovados** pela Meta/Gupshup. Envio de mensagem de template usando o botão aprovado, para `5511935856707`: aceito nos dois parceiros, `wamid`/id reais retornados e persistidos — confirma o ciclo completo (criar → aprovar → enviar). - **Não testado ao vivo:** a resposta real de um contato aceitando o botão — o formato do webhook (`type=contacts`, `origin: contact_request`) está confirmado na documentação oficial da Meta (ver "Formato confirmado" acima), mas só uma revelação real por um usuário final confirma que o comportamento observado bate exatamente com o documentado. ## Limites e dependências - Mensagem interativa livre (`request_contact_info`) só funciona dentro da janela de sessão de 24h — fora dela, é necessário usar o botão em template (já implementado, ver acima). - No envio de mensagem de template, o botão **não precisa ser redeclarado** — o `HandleButtonsUseCase` usado no envio de template é no-op para qualquer tipo de botão (buttons nunca são reenviados no payload de `POST .../messages`), e mesmo assim o botão aparece normalmente, porque a Meta/Gupshup já o conhecem pelo nome+idioma do template aprovado. Confirmado ao vivo. - Depende do rollout de usernames estar habilitado para a conta/número na Meta. - Front-end: criação de template com o botão já implementada; falta uma tela dedicada para a mensagem interativa livre (envio direto, fora de template) — hoje só via API/Bruno/cURL. ## Critérios de aceite - [x] Enviar `request_contact_info` — Meta e Gupshup - [x] Enviar para contato identificado só por `bsuid` (via `userId`) - [x] Testado ao vivo (envio, ambos os parceiros) - [x] Reveal entregue ao cliente final via `NEW_MESSAGE` (sem evento novo) - [x] Criar template com botão `REQUEST_CONTACT_INFO` — testado ao vivo (Meta e Gupshup) - [x] Templates de teste aprovados + envio de mensagem de template com o botão testado ao vivo - [x] Suporte no builder de template do front-end (`templateComponentsBuilder.ts` + `ButtonsConfiguration.tsx`) - [x] Formato do webhook de resposta confirmado na documentação oficial da Meta **e** da Gupshup (`type=contacts`, `origin: contact_request`) - [x] `captureRevealedPhoneNumber()` validado contra o pipeline real, Meta e Gupshup (`ProcessWebhookUseCase`/`NormalizeIncomingWebhookPayloadUseCase`), nos dois cenários (`contact_request` e `other`) - [ ] Validar com um caso real de contato aceitando o compartilhamento - [ ] Tela no front-end para a mensagem interativa livre (envio direto, fora de template) ## Referências - Meta — Business-scoped user IDs / usernames: `developers.facebook.com/documentation/business-messaging/whatsapp/business-scoped-user-ids/` - Gupshup — BSUID, seção "Request Contact Info BSUID Webhook Event": `partner-docs.gupshup.io/docs/bsuid` - [ARCHITECTURE.md — Padrão orquestrador multi-parceiro](../architecture/ARCHITECTURE.md#padrão-orquestrador-multi-parceiro-coreomnimetausecase) - [ARCHITECTURE.md — Contrato de webhook uniforme entre parceiros](../architecture/ARCHITECTURE.md#contrato-de-webhook-uniforme-entre-parceiros) - Bruno (requests de teste): `request-collections/OmniMeta/Bruno/Message/Send Request Contact Info.bru`, `.../Template/Create Template With Request Contact Info Button(.bru|(Gupshup).bru)`, `.../Webhook/Facebook partner - Contact Info Shared (contact_request).bru`, `.../Webhook/Facebook partner - Contact Shared Manually (origin other).bru` — repo irmão `request-collections`, pasta `OmniMeta/Bruno` ## Histórico | Data | Nota | | :--- | :--- | | 2026-09-11 | Envio implementado (Meta e Gupshup) e testado ao vivo contra `5511935856707` | | 2026-09-11 | Ciclo de template fechado ao vivo: criação do botão via API confirmada (Meta e Gupshup), templates de teste aprovados, envio de mensagem de template com o botão confirmado nos dois parceiros; suporte adicionado no front-end (`ButtonsConfiguration.tsx` + `templateComponentsBuilder.ts`) | | 2026-09-11 | Revisão de design: removido o evento de webhook dedicado `CONTACT_PHONE_REVEALED` — o reveal passa a ser tratado como mensagem `contacts` normal, entregue via `NEW_MESSAGE` já existente, sem exigir nova assinatura do cliente nem expor `clientId` no payload | | 2026-09-14 | Confirmado na documentação oficial da Meta (extraído do HTML da página business-scoped-user-ids) o schema exato do webhook de resposta: campo `origin` (`contact_request` vs `other`) e `vcard` omitido quando `origin` é `contact_request`. `captureRevealedPhoneNumber()` corrigido para só gravar o telefone quando `origin === 'contact_request'` — antes gravava cegamente o telefone de qualquer mensagem `contacts`, o que erraria o cadastro se o contato bsuid-only compartilhasse manualmente o cartão de outra pessoa | | 2026-09-14 | Validado o fix rodando os dois payloads (`contact_request` e `other`) direto contra `ProcessWebhookUseCase` no backend local — resultado correto nos dois casos. Criados requests Bruno de teste (envio, criação de template com o botão, e os dois cenários de webhook) em `request-collections/OmniMeta/Bruno` | | 2026-09-14 | Repetido o teste do fix pelo caminho da Gupshup (`NormalizeIncomingWebhookPayloadUseCase` → `ProcessWebhookUseCase`) — resultado idêntico ao da Meta | | 2026-09-14 | Confirmado na documentação oficial da própria Gupshup (`partner-docs.gupshup.io/docs/bsuid`, extraído do HTML cru) o mesmo schema de webhook documentado pela Meta — campo `origin` (`contact_request`/`other`), `vcard` omitido em `contact_request`, com exemplo real de payload deles. Fecha a lacuna de "não confirmado pra Gupshup" que ficou aberta desde a checagem anterior nos changelogs (que não tinham esse detalhe) |