How to use webhooks (Yuzap)

Webhooks are HTTP callbacks configured per account and triggered when certain events happen in Yuzap (e.g., message creation). It is possible to create multiple webhooks per account.

---

How to add a webhook

Go to Settings → Integrations → Webhooks and click Configure.

Click Add new webhook. In the modal:

• Provide the URL that will receive the POST.

• Select the desired events (subscriptions). That way you receive only what is relevant in Yuzap.

Save.

The Yuzap will send a request POST with the payload corresponding to the event.

---

Payload example (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"
  }
}

Notes

• message_type: incoming, outgoing or template.

• content_type: input_select, cards, form or text (when interactive, message_type it will be template).

• content_attributes: object with data specific to the content_type.

---

Payload objects (models)

Account

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

Inbox

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

Contact

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

User

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

Conversation

{
  "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 of messages */ ],
  "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"
}

Message

{
  "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 or Contact Object */
  },
  "account": { /* Account Object */ },
  "conversation": { /* Conversation Object */ },
  "inbox": { /* Inbox Object */ }
}

Generic envelope

{
  "event": "event_name"
  /* Event-specific attributes */
}

---

Webhook events (Yuzap)

Subscribe to these events in the dashboard (or via API) when configuring the webhook.

conversation_created — Conversation created

Triggered when a new conversation is created.

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

conversation_updated — Conversation updated

Triggered when any conversation attribute changes.

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

conversation_status_changed — Conversation status changed

Triggered when the status of the conversation is changed.

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

Note: If you use Agent bot APIs instead of webhooks, this event might not be available in some versions.

message_created — Message created

Triggered when a message is created in a conversation.

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

message_updated — Message updated

Triggered when a message is updated.

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

webwidget_triggered — Web widget opened

Triggered when the end user opens the live chat widget.

{
  "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 — Typing started

When an agent starts typing (private note or message to the customer). Use is_private to differentiate.

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

conversation_typing_off — Typing stopped

When the agent stops typing or leaves the window.

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

---

Best practices

• Security: validate the origin, use HTTPS and (if available) signature/HMAC to verify integrity.

• Retries: return 2xx quickly; for heavy processing, enqueue it and respond 200. Idempotency

• : useid event/and timestamps to avoid duplicates. Observability

• : logHTTP status latency, errors, and body (careful with PII). Versioning

• : treat unknown fields as optional; do not break integrations."event": "message_created"