Como funciona o Hi Broker

  • 7 minute(s) read
Prev Next

Sobre a função

O Hi Broker é o componente responsável por intermediar a comunicação entre a Hi Platform e a Meta (WhatsApp Business Platform). Ele processa disparos de mensagens, captura status de entrega e recebimento e encaminha eventos para os Webhooks configurados pelo cliente.

Com esse recurso, é possível acompanhar toda a jornada de mensagens enviadas e recebidas via WhatsApp, além de manter a rastreabilidade dos eventos e conteúdos trocados.

Veja como fazer

Receive Status from Meta

Este recurso foi desenvolvido para receber e processar as mudanças de status de mensagens — normalmente relacionadas a envios de HSM (Highly Structured Message) — provenientes da Meta (WhatsApp Business Platform). A cada atualização de status recebida, o sistema consolida as informações do evento e as envia para o endpoint configurado pelo cliente via Webhook.

Formato enviado ao Webhook

Sempre que ocorrer um evento, seu endpoint de Webhook receberá um JSON com a seguinte estrutura:

{ 
"payload": { /* ver formatos possíveis abaixo */ }, 
"origin": "string", 
"statuses": { "Dispatch": "string", "Delivered": "string" }, "type": "Delivered", 
"tenantId": "00000000-0000-0000-0000-000000000000", 
"departmentId": "00000000-0000-0000-0000-000000000000", "accountId": "00000000-0000-0000-0000-000000000000", 
"eventId": "string", 
"senderId": "string", 
"userId": "string", 
"eventTimestamp": "2025-08-12T17:03:21Z", 
"broker": "string", 
"errorMessage": "string", 
"errorOrigin": "string" 
}

Campos (topo)

  1. payload (objeto) — obrigatório. Um dos formatos listados na seção “6. Formatos de Payload”.
  2. origin (string) — obrigatório. Origem do evento.
  3. statuses (objeto chave/valor) — opcional. Mapa de status adicionais. 4. type (string) — obrigatório. Um dentre: Dispatch, Sent, Delivered, Read, Failed, Deleted, Replied, DispatchFailed.
  4. tenantId, departmentId, accountId (GUID) — obrigatórios.
  5. eventId, senderId, userId (string) — obrigatórios.
  6. eventTimestamp (string, ISO-8601 UTC) — obrigatório.
  7. broker, errorMessage, errorOrigin — opcionais.

Receive Message from Meta

Este recurso foi desenvolvido para receber, processar e encaminhar ao Webhook do cliente as mensagens recebidas da Meta (WhatsApp Business Platform), enviadas por usuários finais para o número de WhatsApp integrado.
Sempre que um cliente final envia uma mensagem pelo WhatsApp, a Meta repassa esse conteúdo para nosso sistema. Nós tratamos os dados recebidos e encaminhamos o evento para o Webhook configurado pelo cliente.

Formato enviado ao Webhook

Sempre que ocorrer um evento, seu endpoint de Webhook receberá um JSON com a seguinte estrutura:

{ 
"id": "7e5f5c77-3e65-4d53-9f8b-123456789abc", 
"tenantId": "11111111-2222-3333-4444-555555555555", 
"departmentId": "aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee", "destinationDepartmentId": "bbbbbbbb-cccc-dddd-eeee-ffffffffffff", "senderId": "5511999999999", 
"consumerId": "5511888888888", 
"consumerName": "João da Silva", 
"accountId": "99999999-8888-7777-6666-555555555555", 
"orderGaranteeFlag": true, 
"payload": { 
/* Ver formatos possíveis na seção “6. Formatos de Payload” */ }, 
"repliedMessageId": "abcd1234efgh5678", 
"brokerTypeOrigin": "Meta", 
"customerIdentificationProperties": [ 
{ "name": "cpf", "value": "12345678900" }, 
{ "name": "email", "value": "joao.silva@exemplo.com" } ], 
"customProperties": [ 
{ "name": "canal", "value": "whatsapp" } 
], 
"adProperties": [ 
{ "name": "campaignId", "value": "cmp_001" } 
]
}

Campos (topo)

  1. id (GUID) — obrigatório. Identificador único da mensagem.
  2. tenantId (GUID) — obrigatório. Identificador do site/tenant.
  3. departmentId (GUID) — obrigatório. Departamento que recebeu a mensagem. 4. destinationDepartmentId (GUID) — opcional. Departamento de destino, se houver roteamento.
  4. senderId (string) — obrigatório. Identificador do remetente no contexto do canal. 6. consumerId (string) — obrigatório. Identificador do consumidor/usuário final. 7. consumerName (string) — opcional. Nome do consumidor, quando disponível. 8. accountId (GUID) — obrigatório. Conta associada ao atendimento.
  5. orderGaranteeFlag (boolean) — opcional. Indica se a resposta garantirá ordenação. 10. payload (objeto) — obrigatório. Conteúdo da mensagem. Um dos formatos listados na seção “6. Formatos de Payload”.
  6. repliedMessageId (string) — opcional. ID da mensagem à qual o usuário respondeu. 12. brokerTypeOrigin (string/enum) — obrigatório. Origem/broker do evento (ex.: Meta). 13. customerIdentificationProperties (lista de objetos) — opcional. Propriedades de identificação do usuário (chave/valor).
  7. customProperties (lista de objetos) — opcional. Propriedades adicionais associadas ao cliente.
  8. adProperties (lista de objetos) — opcional. Propriedades relacionadas a anúncios/campanhas de origem.

Send Message to Meta

Este é um endpoint recém-criado para o envio de mensagens originadas pelo broker, utilizadas como resposta a mensagens recebidas de clientes finais via WhatsApp. Diferente do fluxo de HSM (Highly Structured Message), este endpoint é voltado exclusivamente para o envio de mensagens que dão continuidade a uma conversa já existente, iniciada pelo próprio usuário final. A requisição deve ser feita via POST para a URL:

api/webhooks/outbound/{accountId}

onde {accountId} é um parâmetro obrigatório na rota que identifica a conta responsável pelo envio. Este endpoint permite encaminhar textos, mídias ou interativos de forma síncrona ao atendimento, preservando o contexto da conversa e mantendo a rastreabilidade com base nos identificadores de mensagem e de conta.

Formato enviado a API

API deverá enviar um JSON com a seguinte estrutura:

{ 
"id": "7e5f5c77-3e65-4d53-9f8b-123456789abc", 
"tenantId": "11111111-2222-3333-4444-555555555555", 
"departmentId": "aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee", "destinationDepartmentId": "bbbbbbbb-cccc-dddd-eeee-ffffffffffff", "senderId": "5511999999999", 
"userId": "5511888888888", 
"protocol": "PRT-2025-0001", 
"payload": [ 
{ 
"type": "Text", 
"body": "Olá! Seu pedido foi confirmado.", 
"previewFirstUrl": false 
} 
], 
"origin": "System", 
"customProperties": [ 
{ "name": "orderId", "value": "ORD-123" }, 
{ "name": "canal", "value": "whatsapp" } 
] 
}

Campos (request body)

  1. id (GUID) — obrigatório. Identificador único da mensagem.
  2. tenantId (GUID) — obrigatório. Identificador do site/tenant.
  3. departmentId (GUID) — obrigatório. DepartmentId da configuração do WhatsApp Connect.
  4. destinationDepartmentId (GUID) — opcional. Departamento onde a mensagem foi/será tratada (roteamento interno).
  5. senderId (string) — obrigatório. Identificador do remetente no canal. 6. userId (string) — obrigatório. Identificador do destinatário (ex.: número/ID do contato no WhatsApp).
  6. protocol (string) — opcional. Protocolo interno para rastreabilidade.
  7. payload (lista de objetos) — obrigatório. Um ou mais itens; cada item deve seguir “6. Formatos de Payload”.
  8. origin (string/enum MessageOrigin) — obrigatório. Origem da mensagem (ex.: System, Operator, Automation).
  9. customProperties (lista de Property) — opcional. Metadados adicionais (pares chave/valor).

Formatos de Payload

O campo payload no JSON enviado pelo Webhook pode variar conforme o tipo de conteúdo. Abaixo estão os formatos possíveis e suas regras:

Texto

Campos:
● body (string) — até 4096 caracteres, obrigatório.
● previewFirstUrl (boolean) — opcional.
● identifier (string) — opcional.
● data (objeto chave/valor) — opcional.

Regra principal: body não pode ultrapassar 4096 caracteres.

Imagem

Campos:
● imageType (string) — obrigatório.
● url (string) — obrigatório.
● caption (string) — opcional.
● contentType (string) — derivado do imageType.
● identifier e data — opcionais.
Regra principal: url é obrigatório.

Áudio

Campos:
● audioType (string) — obrigatório.
● url (string) — obrigatório.
● contentType (string) — derivado do audioType.
● identifier e data — opcionais.
Regra principal: url é obrigatório.

Vídeo

Campos:
● videoType (string) — obrigatório.
● url (string) — obrigatório.
● caption (string) — opcional.
● contentType (string) — derivado do videoType.
● identifier e data — opcionais.

Documento

Campos:
● documentType (string) — obrigatório.
● url (string) — obrigatório.
● caption (string) — opcional.
● filename (string) — opcional.
● contentType (string) — mapeado a partir do documentType (PDF, MSPOWERPOINT, MSWORD, MSEXCEL, TXT).
● identifier e data — opcionais.

HSM (Message Template)

Campos:
● isTemplate (boolean) — obrigatório.
● category (string) — opcional.
● namespace (string) — obrigatório.
● elementName (string) — obrigatório.
● externalLabel (string) — opcional.
● localizableParams (lista de objetos) — opcional.
● localizableParamsReduced (lista de strings) — derivado de localizableParams. ● namedParams (objeto chave/valor) — derivado de localizableParams. ● components — opcional.
● stagingConfiguration — opcional.
● identifier e data — opcionais.

Interativo — Botões

Campos:
● type (string) — sempre "Button".
● header, body, footer — opcionais (respeitando limites de caracteres: body ≤ 1024, footer ≤ 60).
● action (lista) — entre 1 e 3 botões, IDs únicos.
● identifier e data — opcionais.

Interativo — Lista

Campos:
● type (string) — sempre "List".
● header, body, footer — opcionais.
● textButton (string) — obrigatório.
● action (lista de seções, cada seção com título e linhas).
● identifier e data — opcionais.

Interativo — Catálogo (produto único)

Campos:
● type (string) — sempre "Product".
● header, body, footer — opcionais.
● action — deve conter catalogId e productRetailerId.
● identifier e data — opcionais.

Interativo — Catálogo (lista de produtos)

Campos:
● type (string) — sempre "ProductList".
● header, body, footer — opcionais.
● catalogId (string) — obrigatório.
● action — lista de seções com produtos.
● identifier e data — opcionais.

Quick Replies (Messenger)

Campos:
● body (string) — obrigatório.
● quickReplies (lista de objetos) — obrigatório (1 a 13 itens).
● Cada quickReply precisa ter title e payload, imageUrl é opcional.
● identifier e data — opcionais.

Acionadores / Transferência de atendimento

Transferência para canal principal
● triggerType = "HeadChannel".
● notifyChannel (boolean) — opcional.
● data (objeto) — opcional.
● identifier — opcional.

Inicialização de relatórios
● triggerType = "InitReports".
● protocol (string) — obrigatório.
● notifyChannel (boolean) — opcional.
● data (objeto) — opcional.
● identifier — opcional.

Transferência de canal/departamento
● triggerType = "TransferChannel".
● destinationDepartmentId (GUID) — obrigatório.
● destinationChannel (string) — obrigatório.
● notifyChannel (boolean) — opcional.
● data (objeto) — opcional.
● identifier — opcional.

Perguntas frequentes