Como usar webhooks (Yuzap)

Última atualização: 09 de maio de 2025

Webhooks são callbacks HTTP configurados por conta e disparados quando certos eventos acontecem no Yuzap (ex.: criação de mensagem). É possível criar vários webhooks por conta.

---

Como adicionar um webhook

1. Acesse Configurações → Integrações → Webhooks e clique em Configurar.

2. Clique em Adicionar novo webhook. No modal:

   • Informe a URL que receberá as requisições POST.

   • Selecione os eventos desejados (assinaturas). Assim você recebe apenas o que é relevante no Yuzap.

3. Salve.

O Yuzap enviará uma requisição POST com a carga útil (payload) correspondente ao evento.

---

Exemplo de payload (message_created)

{
  "event": "message_created",
  "id": "1",
  "content": "Hi",
  "created_at": "2020-03-03 13:05:57 UTC",
  "message_type": "incoming",
  "content_type": "enum",
  "content_attributes": {},
  "source_id": "",
  "sender": {
    "id": "1",
    "name": "Agent",
    "email": "[email protected]"
  },
  "contact": {
    "id": "1",
    "name": "contact-name"
  },
  "conversation": {
    "display_id": "1",
    "additional_attributes": {
      "browser": {
        "device_name": "Macbook",
        "browser_name": "Chrome",
        "platform_name": "Macintosh",
        "browser_version": "80.0.3987.122",
        "platform_version": "10.15.2"
      },
      "referer": "http://www.yuzap.com",
      "initiated_at": "Tue Mar 03 2020 18:37:38 GMT-0700 (Mountain Standard Time)"
    }
  },
  "account": {
    "id": "1",
    "name": "Yuzap"
  }
}

Observações

• message_type: incoming, outgoing ou template.

• content_type: input_select, cards, form ou text (quando interativo, message_type será template).

• content_attributes: objeto com dados específicos ao content_type.

---

Objetos de payload (modelos)

Conta

{ "id": "integer", "name": "string" }

Caixa de entrada (Inbox)

{ "id": "integer", "name": "string" }

Contato

{
  "id": "integer",
  "name": "string",
  "avatar": "string",
  "type": "contact",
  "account": { /* Account Object */ }
}

Usuário

{
  "id": "integer",
  "name": "string",
  "email": "string",
  "type": "user"
}

Conversa

{
  "additional_attributes": {
    "browser": {
      "device_name": "string",
      "browser_name": "string",
      "platform_name": "string",
      "browser_version": "string",
      "platform_version": "string"
    },
    "referer": "string",
    "initiated_at": { "timestamp": "iso-datetime" }
  },
  "can_reply": "boolean",
  "channel": "string",
  "id": "integer",
  "inbox_id": "integer",
  "contact_inbox": {
    "id": "integer",
    "contact_id": "integer",
    "inbox_id": "integer",
    "source_id": "string",
    "created_at": "datetime",
    "updated_at": "datetime",
    "hmac_verified": "boolean"
  },
  "messages": [ /* Array de mensagens */ ],
  "meta": {
    "sender": { /* Contact Object */ },
    "assignee": { /* User Object */ }
  },
  "status": "string",
  "unread_count": "integer",
  "agent_last_seen_at": "unix-timestamp",
  "contact_last_seen_at": "unix-timestamp",
  "timestamp": "unix-timestamp",
  "account_id": "integer"
}

Mensagem

{
  "id": "integer",
  "content": "string",
  "message_type": "integer",
  "created_at": "unix-timestamp",
  "private": "boolean",
  "source_id": "string or null",
  "content_type": "string",
  "content_attributes": "object",
  "sender": {
    "type": "contact|user"
    /* User ou Contact Object */
  },
  "account": { /* Account Object */ },
  "conversation": { /* Conversation Object */ },
  "inbox": { /* Inbox Object */ }
}

Envelope genérico

{
  "event": "event_name"
  /* Atributos específicos do evento */
}

---

Eventos de webhook (Yuzap)

Assine estes eventos no painel (ou via API) ao configurar o webhook.

conversation_created — Conversa criada

Disparado quando uma nova conversa é criada.

{
  "event": "conversation_created"
  /* ...Conversation Attributes */
}

conversation_updated — Conversa atualizada

Disparado quando algum atributo da conversa muda.

{
  "event": "conversation_updated",
  "changed_attributes": [
    {
      "<attribute_name>": {
        "current_value": "",
        "previous_value": ""
      }
    }
  ]
  /* ...Conversation Attributes */
}

conversation_status_changed — Status da conversação alterado

Disparado quando o status da conversa é alterado.

{
  "event": "conversation_status_changed"
  /* ...Conversation Attributes */
}

Observação: Se você usa APIs de bot de agente em vez de webhooks, este evento pode não estar disponível em algumas versões.

message_created — Mensagem criada

Disparado quando uma mensagem é criada em uma conversa.

{
  "event": "message_created"
  /* ...Message Attributes */
}

message_updated — Mensagem atualizada

Disparado quando uma mensagem é atualizada.

{
  "event": "message_updated"
  /* ...Message Attributes */
}

webwidget_triggered — Widget web aberto

Disparado quando o usuário final abre o widget de chat ao vivo.

{
  "event": "webwidget_triggered",
  "id": "",
  "contact": { /* Contact Object */ },
  "inbox": { /* Inbox Object */ },
  "account": { /* Account Object */ },
  "current_conversation": { /* Conversation Object */ },
  "source_id": "string",
  "event_info": {
    "initiated_at": { "timestamp": "date-string" },
    "referer": "string",
    "widget_language": "string",
    "browser_language": "string",
    "browser": {
      "browser_name": "string",
      "browser_version": "string",
      "device_name": "string",
      "platform_name": "string",
      "platform_version": "string"
    }
  }
}

conversation_typing_on — Digitação iniciada

Quando um agente começa a digitar (nota privada ou mensagem ao cliente). Use is_private para diferenciar.

{
  "event": "conversation_typing_on",
  "conversation": { /* Conversation Object */ },
  "user": { /* User / AgentBot / Captain Object */ },
  "is_private": true
}

conversation_typing_off — Digitação encerrada

Quando o agente para de digitar ou sai da janela.

{
  "event": "conversation_typing_off",
  "conversation": { /* Conversation Object */ },
  "user": { /* User / AgentBot / Captain Object */ },
  "is_private": true
}

---

Boas práticas

• Segurança: valide a origem, use HTTPS e (se disponível) assinatura/HMAC para verificar integridade.

• Retentativas: retorne 2xx rapidamente; para processamento pesado, coloque em fila e responda 200.

• Idempotência: use id/event e timestamps para evitar duplicidades.

• Observabilidade: logue status HTTP, latência, erros e body (com cuidado a PII).

• Versionamento: trate campos desconhecidos como opcionais; não quebre integrações.

---

Checklist rápido

• Criei o webhook em Configurações → Integrações → Webhooks

• Escolhi a URL pública (HTTPS) e assinei apenas os eventos necessários

• Valido assinatura/origem e retorno 2xx rapidamente

• Implementei retentativa/fila e idempotência

• Monitoração ativa (logs, alertas, DLQ)

Pronto! Seus webhooks do Yuzap estão configurados para transmitir eventos em tempo real ao seu backend — com segurança e confiabilidade.

Pensamento estendido