Metadata

Como o metadata da sessão armazena informações de roteamento específicas do canal

O metadata da sessão é um dicionário arbitrário de chave-valor que sua integração usa para armazenar dados específicos do canal necessários para o roteamento de mensagens. É assim que a Antonnia sabe para onde entregar mensagens de saída.

Por que o metadata é importante

Quando a Antonnia dispara um webhook message.created, seu handler precisa saber:

Qual instância do canal usar para enviar (ex.: qual número de WhatsApp)
Para qual usuário final entregar (ex.: número de telefone ou ID do ticket)

Essa informação fica em session.metadata.

Convenção

Cada canal usa um prefixo para organizar suas chaves de metadata por namespace:

{
  "whatsapp_phone_number": "5511999888777",
  "whatsapp_phone_number_id": "phone_id_123"
}

HubSpot

{
  "hubspot_ticket_id": "ticket_456",
  "hubspot_thread_id": "thread_789",
  "hubspot_channel_account_id": "account_001",
  "hubspot_portal_id": "portal_123",
  "hubspot_sender_id": "sender_456"
}

ZAPI

{
  "zapi_instance_id": "instance_123",
  "zapi_phone": "5511999888777"
}

Seu canal

Siga o mesmo padrão — prefixe todas as chaves com o nome do seu canal:

{
  "mychannel_user_id": "ext_user_456",
  "mychannel_instance_id": "inst_789"
}

Definindo metadata

O metadata é definido na criação da sessão e pode ser atualizado posteriormente:

// On creation
POST /sessions
{
  "contact_id": "user_123",
  "contact_name": "Jane Doe",
  "agent_id": "agent_abc",
  "metadata": {
    "mychannel_user_id": "ext_user_456",
    "mychannel_instance_id": "inst_789"
  }
}

// Update later
PATCH /sessions/{session_id}
{
  "fields": {
    "metadata": {
      "mychannel_user_id": "ext_user_456",
      "mychannel_instance_id": "inst_789",
      "mychannel_ticket_id": "ticket_001"
    }
  }
}

Atualizações de metadata substituem o objeto de metadata inteiro. Sempre inclua todas as chaves existentes ao atualizar, ou você perderá dados armazenados anteriormente.

Lendo metadata nos webhooks

Ao processar webhooks de saída, busque a sessão para obter o metadata de roteamento:

# In your message.created webhook handler
session = httpx.get(
    f"{BASE_URL}/sessions/{message['session_id']}",
    headers=HEADERS,
).json()

channel_user_id = session["metadata"]["mychannel_user_id"]
instance_id = session["metadata"]["mychannel_instance_id"]

# Now send the message through your channel API
send_to_my_channel(instance_id, channel_user_id, message["content"])

Metadata para busca de sessões

Use filtros de metadata em POST /sessions/search para encontrar sessões de uma instância de canal específica:

POST /sessions/search
{
  "contact_id": "user_123",
  "status": "open",
  "metadata": {
    "mychannel_instance_id": "inst_789"
  }
}

Isso evita colisões entre canais quando um contato tem sessões em múltiplos canais.

Metadata

On this page