Pular para o conteúdo
Matra Meta Hub
Páginas da documentação

Visão geral

O que o Matra Meta Hub faz, como um app se integra e o que pedir à equipe Matra antes de começar.

Abrir o Markdown

O Matra Meta Hub é a camada entre os apps da Matra e as APIs da Meta. Ele concentra o app aprovado na Meta e expõe uma API REST e webhooks assinados. Assim, o seu app não fala com a Graph API, não guarda token da Meta e não passa por revisão de app própria.

Hoje o hub cobre o WhatsApp Cloud API: conexão do número do cliente (inclusive Coexistence, com o app WhatsApp Business no celular), mensagens recebidas e enviadas, mídia, status de entrega, templates, janela de atendimento e custos. Instagram Direct, Messenger e Lead Ads estão planejados.

Endereços

O quê URL
API (base de todas as rotas) https://api.metahub.matratecnologia.com/v1
Documentação https://metahub.matratecnologia.com/docs
Índice para IA https://metahub.matratecnologia.com/llms.txt
Documentação inteira num arquivo https://metahub.matratecnologia.com/llms-full.txt
OpenAPI 3 das rotas /v1 https://metahub.matratecnologia.com/docs/openapi.json

Conceitos

Termo O que é
App consumidor O seu sistema (um CRM, um SaaS). Tem chaves de API, um endpoint de webhook e uma lista de URLs de retorno
Workspace Um cliente final do seu app. Você o cria pela API com o id que ele tem no seu sistema (externalId)
Conexão Um número de WhatsApp Business ligado a um workspace. Nasce quando o cliente conclui o fluxo da Meta na página de conexão do hub
Evento Algo que aconteceu (mensagem recebida, status de entrega, conexão criada). Chega ao seu app por webhook assinado
Entrega Uma tentativa de levar um evento ao seu webhook. Tem reentrega automática e reenvio manual

Como a integração funciona

  1. Workspace. O seu backend cria um workspace para o cliente: POST /v1/workspaces.
  2. Sessão de conexão. O backend abre uma sessão (POST /v1/workspaces/:id/connect-sessions) e manda o cliente para a url devolvida, uma página do hub com o fluxo oficial da Meta (Embedded Signup).
  3. Retorno. Ao terminar, o navegador volta para o seu returnUrl com ?status=connected&connectionId=.... A confirmação de verdade é o evento connection.created no seu webhook.
  4. Ativação. O hub ativa o número em segundo plano. Quando termina, chega connection.updated com status: "active".
  5. Conversa. Mensagens recebidas chegam como whatsapp.message.received. Para responder, use POST /v1/connections/:id/messages. O resultado do envio chega como whatsapp.message.status.
Seu backend ──POST /v1/workspaces──────────────▶ Hub
Seu backend ──POST …/connect-sessions──────────▶ Hub ──▶ url da página de conexão
Cliente     ──abre a url, conclui o fluxo da Meta──▶ volta ao seu returnUrl
Hub         ──webhook connection.created / .updated──▶ seu endpoint
Hub         ──webhook whatsapp.message.received──────▶ seu endpoint
Seu backend ──POST …/messages (Idempotency-Key)──▶ Hub ──▶ Meta
Hub         ──webhook whatsapp.message.status────────▶ seu endpoint

O que pedir à equipe Matra

Antes da primeira chamada, a equipe Matra cadastra o seu app no hub e entrega:

  • Chave de API (mh_live_...), mostrada uma única vez. Guarde num cofre de segredos, só no backend.
  • Endpoint de webhook: a equipe cadastra a URL que você informar (HTTPS público, sem redirect) e entrega o segredo de assinatura (whsec_...), também mostrado uma vez.
  • URLs de retorno: a lista de returnUrl aceitas na sessão de conexão. A comparação ignora query e fragmento.

Contato: matratecnologia@gmail.com ou WhatsApp +55 (43) 99914-0409.

Regras que valem em toda a API

  • Autenticação: Authorization: Bearer <chave> em toda rota de /v1. A API é server-to-server: nunca chame do navegador.
  • Erros: decida pelo campo code da resposta, nunca pela message (ela vem traduzida).
  • Recurso de outro app: responde 404, nunca 403.
  • Envio de mensagem: exige o header Idempotency-Key. Repetir com a mesma chave não envia de novo.
  • Webhooks:
    • assinados com HMAC-SHA256 sobre `${x-hub-timestamp}.${corpo cru}`;
    • entrega "pelo menos uma vez": deduplique pelo id do envelope;
    • a ordem de chegada não é garantida.
  • Conteúdo: nenhuma resposta ou evento de status traz token, PIN ou credencial da Meta. As respostas de envio não trazem o conteúdo da mensagem nem o destinatário.

Próximos passos