Como funciona o Hi Broker

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

Gerenciamento do disparo de mensagem

Hi Broker Public API v1

API pública para gerenciamento de modelos de mensagens do WhatsApp Business (WABA) através da integração com o Cloud API (Broker).

Objetivo

Disponibilizar uma camada pública e segura para que os clientes possam gerenciar seus templates META diretamente via API.

Swagger

Hi Broker Public API:
https://whatsapp-connect.hiplatform.com/hsmservices/swagger/index.html

Endereço base

URL:
https://whatsapp-connect.hiplatform.com/hsmservices/api/

Autenticação

Todas as requisições exigem o header de autenticação obrigatório:

Authorization: Bearer {DT-Fenix-Token} ou Basic {AuthorizationToken}

MessageTemplates

GET

/api/public/message_templates/{wabaId}

GET

/api/public/message_templates/{wabaId}/{id}

POST

/api/public/message_templates/{wabaId}

PATCH

/api/public/message_templates/{wabaId}/{id}

Cria um novo template de mensagem.

Descrição:
Permite atualizar um template existente.

Limitações:

Apenas templates com status APPROVED, REJECTED ou PAUSED podem ser editados.
Somente é possível editar a categoria, componentes ou tempo de vida do template.
Não é possível editar componentes individuais; todos os componentes existentes serão substituídos pelos enviados na requisição.
Não é possível alterar a categoria de um template aprovado.
Templates aprovados podem ser editados até 10 vezes em um período de 30 dias, ou 1 vez em 24 horas.
Templates rejeitados ou pausados podem ser editados ilimitadamente.
Após a edição de um template aprovado ou pausado, ele será automaticamente aprovado, a menos que falhe na revisão do template.

Consulte a documentação oficial da Meta para mais informações:
Template components

Nome	Tipo	Descrição
wabaId *	string	ID da conta WABA.
id *	string	ID do template.

Requisição:

{
  "components": [
    {
      "type": "HEADER",
      "format": "TEXT",
      "text": "Our {{1}} is on!",
      "example": {
        "header_text": [
          "Spring Sale"
        ]
      }
    },
    {
      "type": "BODY",
      "text": "Shop now through {{1}} and use code {{2}} to get {{3}} off of all merchandise.",
      "example": {
        "body_text": [
          [
            "the end of April",
            "25OFF",
            "25%"
          ]
        ]
      }
    },
    {
      "type": "FOOTER",
      "text": "Use the buttons below to manage your marketing subscriptions"
    },
    {
      "type": "BUTTONS",
      "buttons": [
        {
          "type": "QUICK_REPLY",
          "text": "Unsubscribe from Promos"
        },
        {
          "type": "URL",
          "text": "QUICK_REPLY",
          "url": "Unsubscribe from All"
        }
      ]
    }
  ]
}

Retornos:

Código	Status
200	OK

{
  "success": true
}

Código	Status
400	Bad Request

{
  "message": "string",
  "type": "string",
  "code": 0,
  "error_subcode": 0,
  "is_transient": true,
  "error_user_title": "string",
  "error_user_msg": "string",
  "fbtrace_id": "string"
}

Código	Status
404	Not Found

{
  "message": "string",
  "type": "string",
  "code": 0,
  "error_subcode": 0,
  "is_transient": true,
  "error_user_title": "string",
  "error_user_msg": "string",
  "fbtrace_id": "string"
}

DELETE

/api/public/message_templates/{wabaId}

DELETE

/api/public/message_templates/{wabaId}/{id}

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)

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

id (GUID) — obrigatório. Identificador único da mensagem.
tenantId (GUID) — obrigatório. Identificador do site/tenant.
departmentId (GUID) — obrigatório. Departamento que recebeu a mensagem. 4. destinationDepartmentId (GUID) — opcional. Departamento de destino, se houver roteamento.
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.
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”.
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).
customProperties (lista de objetos) — opcional. Propriedades adicionais associadas ao cliente.
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)

id (GUID) — obrigatório. Identificador único da mensagem.
tenantId (GUID) — obrigatório. Identificador do site/tenant.
departmentId (GUID) — obrigatório. DepartmentId da configuração do WhatsApp Connect.
destinationDepartmentId (GUID) — opcional. Departamento onde a mensagem foi/será tratada (roteamento interno).
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).
protocol (string) — opcional. Protocolo interno para rastreabilidade.
payload (lista de objetos) — obrigatório. Um ou mais itens; cada item deve seguir “6. Formatos de Payload”.
origin (string/enum MessageOrigin) — obrigatório. Origem da mensagem (ex.: System, Operator, Automation).
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.

Como funciona o Hi Broker

Sobre a função

Veja como fazer

Gerenciamento do disparo de mensagem

Hi Broker Public API v1

Objetivo

Swagger

Endereço base

Autenticação

MessageTemplates

Receive Status from Meta

Formato enviado ao Webhook

Campos (topo)

Receive Message from Meta

Formato enviado ao Webhook

Campos (topo)

Send Message to Meta

Formato enviado a API

Campos (request body)

Formatos de Payload

Texto

Imagem

Áudio

Vídeo

Documento

HSM (Message Template)

Interativo — Botões

Interativo — Lista

Interativo — Catálogo (produto único)

Interativo — Catálogo (lista de produtos)

Quick Replies (Messenger)

Acionadores / Transferência de atendimento

Perguntas frequentes