Events¶
All bodies share the envelope.
| Event | When it is sent | Who gets it |
|---|---|---|
lead.created |
A visitor leaves contact details and becomes a lead. | Every business |
lead.updated |
A lead's status or owner changes. | Every business |
conversation.closed |
A conversation ends, with its summary, topic and sentiment. | Every business |
ticket.created |
A ticket is opened, including each hand-over to your team, with the chat summary. | Every business |
ticket.updated |
A ticket's status, priority, assignee or tags change. | Every business |
meeting.booked |
A customer books a meeting in chat. | Businesses that take bookings |
meeting.cancelled |
A booked meeting is cancelled. | Businesses that take bookings |
order.created |
A customer places an order in chat. | Shops only |
order.updated |
An order's status, payment, customer details or courier changes, or the shopper asks for a return or exchange. | Shops only |
Examples are what Send test event sends. Use id to skip repeats.
lead.created¶
Sent once per lead. lead_url and conversation_url open it in the dashboard.
{
"event": "lead.created",
"id": "00000000-0000-4000-8000-000000000000",
"created_at": "2026-10-17T09:30:00+00:00",
"lead": {
"id": 101,
"name": "Test customer",
"email": "test@example.com",
"phone": "+8801700000000",
"channel": "widget",
"status": "new",
"owner": "Your teammate",
"tags": [
"Sales"
],
"requirement": [
"Wants a quote for 20 units"
],
"answers": {},
"lead_score": 72,
"buying_intent_score": 65,
"created_at": "2026-10-17T09:30:00+00:00",
"conversation_url": "https://kothok.ai/dashboard/conversations/?session=a1b2c3d4-sample",
"lead_url": "https://kothok.ai/dashboard/leads/?lead=101"
}
}
lead.updated¶
changes: status, owner, contact or merged.
{
"event": "lead.updated",
"id": "00000000-0000-4000-8000-000000000000",
"created_at": "2026-10-17T09:30:00+00:00",
"lead": {
"id": 101,
"name": "Test customer",
"email": "test@example.com",
"phone": "+8801700000000",
"channel": "widget",
"status": "new",
"owner": "Your teammate",
"tags": [
"Sales"
],
"requirement": [
"Wants a quote for 20 units"
],
"answers": {},
"lead_score": 72,
"buying_intent_score": 65,
"created_at": "2026-10-17T09:30:00+00:00",
"conversation_url": "https://kothok.ai/dashboard/conversations/?session=a1b2c3d4-sample",
"lead_url": "https://kothok.ai/dashboard/leads/?lead=101"
},
"changes": [
"status"
]
}
conversation.closed¶
Includes summary, topic, sentiment and resolved.
{
"event": "conversation.closed",
"id": "00000000-0000-4000-8000-000000000000",
"created_at": "2026-10-17T09:30:00+00:00",
"conversation": {
"session_id": "a1b2c3d4-sample",
"channel": "widget",
"title": "Asks about bulk pricing",
"customer": {
"name": "Test customer",
"email": "test@example.com",
"phone": "+8801700000000"
},
"summary": "Asked about bulk pricing; the team sent a quote.",
"started_at": "2026-10-17T09:30:00+00:00",
"conversation_url": "https://kothok.ai/dashboard/conversations/?session=a1b2c3d4-sample",
"resolved": true,
"topic": "Sales",
"sentiment": 4,
"ended_at": "2026-10-17T09:30:00+00:00"
}
}
ticket.created¶
Sent about 45 seconds after a hand-over, so it includes the chat summary and contact details.
{
"event": "ticket.created",
"id": "00000000-0000-4000-8000-000000000000",
"created_at": "2026-10-17T09:30:00+00:00",
"ticket": {
"id": 42,
"session_id": "a1b2c3d4-sample",
"channel": "widget",
"status": "open",
"priority": "high",
"reason": "Asked for a person: bulk order",
"assignee": "Your teammate",
"tags": [
"handoff"
],
"customer": {
"name": "Test customer",
"email": "test@example.com",
"phone": "+8801700000000"
},
"summary": "Wants 20 units delivered next week and asked to speak to someone.",
"created_at": "2026-10-17T09:30:00+00:00",
"resolved_at": null,
"ticket_url": "https://kothok.ai/dashboard/tickets/?ticket=42",
"conversation_url": "https://kothok.ai/dashboard/conversations/?session=a1b2c3d4-sample"
}
}
ticket.updated¶
changes sits inside ticket: status, priority, assignee, tags.
{
"event": "ticket.updated",
"id": "00000000-0000-4000-8000-000000000000",
"created_at": "2026-10-17T09:30:00+00:00",
"ticket": {
"id": 42,
"session_id": "a1b2c3d4-sample",
"channel": "widget",
"status": "open",
"priority": "high",
"reason": "Asked for a person: bulk order",
"assignee": "Your teammate",
"tags": [
"handoff"
],
"customer": {
"name": "Test customer",
"email": "test@example.com",
"phone": "+8801700000000"
},
"summary": "Wants 20 units delivered next week and asked to speak to someone.",
"created_at": "2026-10-17T09:30:00+00:00",
"resolved_at": null,
"ticket_url": "https://kothok.ai/dashboard/tickets/?ticket=42",
"conversation_url": "https://kothok.ai/dashboard/conversations/?session=a1b2c3d4-sample",
"changes": [
"status",
"assignee"
]
}
}
meeting.booked¶
Needs Google Calendar connected. starts_at and ends_at are in the meeting's timezone. status is confirmed, or failed if nobody could be notified. Rescheduling sends no event.
{
"event": "meeting.booked",
"id": "00000000-0000-4000-8000-000000000000",
"created_at": "2026-10-17T09:30:00+00:00",
"meeting": {
"booking_id": "bk_sample",
"status": "confirmed",
"topic": "Product demo",
"channel": "widget",
"starts_at": "2026-11-03T15:00:00+06:00",
"ends_at": "2026-11-03T15:30:00+06:00",
"timezone": "Asia/Dhaka",
"attendee": {
"name": "Test customer",
"email": "test@example.com",
"phone": "+8801700000000"
},
"guests": [],
"meeting_link": "https://meet.google.com/abc-defg-hij",
"session_id": "a1b2c3d4-sample",
"conversation_url": "https://kothok.ai/dashboard/conversations/?session=a1b2c3d4-sample"
}
}
meeting.cancelled¶
The same body as meeting.booked, with status: "cancelled", cancelled_at and cancel_reason (null when no reason was given).
{
"event": "meeting.cancelled",
"id": "00000000-0000-4000-8000-000000000000",
"created_at": "2026-10-17T09:30:00+00:00",
"meeting": {
"booking_id": "bk_sample",
"status": "cancelled",
"topic": "Product demo",
"channel": "widget",
"starts_at": "2026-11-03T15:00:00+06:00",
"ends_at": "2026-11-03T15:30:00+06:00",
"timezone": "Asia/Dhaka",
"attendee": {
"name": "Test customer",
"email": "test@example.com",
"phone": "+8801700000000"
},
"guests": [],
"meeting_link": "https://meet.google.com/abc-defg-hij",
"session_id": "a1b2c3d4-sample",
"conversation_url": "https://kothok.ai/dashboard/conversations/?session=a1b2c3d4-sample",
"cancelled_at": "2026-10-17T09:30:00+00:00",
"cancel_reason": "Can't make it"
}
}
order.created¶
Sent once per order. Shown with every optional field ticked. See Order API → Fields.
{
"event": "order.created",
"id": "00000000-0000-4000-8000-000000000000",
"created_at": "2026-10-17T09:30:00+00:00",
"order": {
"order_ref": "KO-TEST01",
"status": "new",
"created_at": "2026-10-17T09:30:00+00:00",
"updated_at": null,
"customer": {
"name": "Test customer",
"phone": "+8801700000000",
"address": "House 1, Road 1, Dhaka",
"email": "test@example.com"
},
"items": [
{
"title": "Sample T-shirt",
"quantity": 2,
"unit_price": 750.0,
"currency": "BDT",
"size": "M",
"color": "Black",
"option": null,
"url": "https://example.com/products/sample-t-shirt"
}
],
"total": 1410.0,
"currency": "BDT",
"discount": {
"code": "EID10",
"amount": 150.0
},
"note": "This is a test order from Kothok.",
"delivery": {
"label": "Inside Dhaka",
"amount": 60.0
},
"payment": {
"method": "cod",
"status": "cod",
"provider": null,
"amount_paid": null
},
"channel": "widget"
}
}
order.updated¶
See Order API → Events for changes, source and request.
{
"event": "order.updated",
"id": "00000000-0000-4000-8000-000000000000",
"created_at": "2026-10-17T09:30:00+00:00",
"order": {
"order_ref": "KO-TEST01",
"status": "new",
"created_at": "2026-10-17T09:30:00+00:00",
"updated_at": null,
"customer": {
"name": "Test customer",
"phone": "+8801700000000",
"address": "House 1, Road 1, Dhaka",
"email": "test@example.com"
},
"items": [
{
"title": "Sample T-shirt",
"quantity": 2,
"unit_price": 750.0,
"currency": "BDT",
"size": "M",
"color": "Black",
"option": null,
"url": "https://example.com/products/sample-t-shirt"
}
],
"total": 1410.0,
"currency": "BDT",
"discount": {
"code": "EID10",
"amount": 150.0
},
"note": "This is a test order from Kothok.",
"delivery": {
"label": "Inside Dhaka",
"amount": 60.0
},
"payment": {
"method": "cod",
"status": "cod",
"provider": null,
"amount_paid": null
},
"channel": "widget"
},
"changes": [
"status"
],
"source": "dashboard"
}