> ## Documentation Index
> Fetch the complete documentation index at: https://docs.adsera.in/llms.txt
> Use this file to discover all available pages before exploring further.

# Addy events

> addy.handoff and addy.lead_updated, field by field.

These events come from **Addy**, AdsEra's AI WhatsApp agent. They cover your whole account; the numbers selected on the webhook don't filter them. Tick them in [Settings → Webhooks](https://app.adsera.in/setting/webhooks).

Both events send the same object: Addy's view of the customer.

| Field | Type | Meaning |
| - | - | - |
| `contact` | string | The customer's phone, for example `919876543210`. |
| `contactId` | string | AdsEra's id for the contact. |
| `whatsapp` | string | Id of your WhatsApp number the chat is on. |
| `status` | string | `active` (Addy is talking), `handed_off` (passed to your team) or `paused`. |
| `summary` | string \| null | What the chat has been about so far. |
| `learned` | object | The customer's answers to Addy's qualifying questions, for example `{ "team_size": "3", "timeline": "this month" }`. |
| `lead.score` | number | 0–100. |
| `lead.temperature` | string | `cold`, `warm` or `hot`. |
| `lead.stage` | string | `new`, `engaged`, `qualified`, `hot`, `booked`, `ordered`, `paid` or `lost`. |
| `lead.reason` | string \| null | Why Addy scored them this way, in a sentence. |
| `handoff` | object \| null | The last hand-off: `reason`, `summary`, `at`. |
| `booked` | boolean | Addy booked a meeting with them. |
| `order` | object \| null | The order Addy took: `status` (`pending`, `paid`, `failed`), `total`, `currency`, `via`, `at`, `paidAt`. |
| `replies` | number | Messages Addy has sent in the chat. |
| `lastCustomerMessageAt`, `lastReplyAt` | date \| null | The customer's last message and Addy's last reply. |

## addy.handoff

Addy passed a chat to your team: the customer asked for a person, or Addy couldn't help. Use it to alert the right salesperson in your CRM.

```json theme={null}
{
  "event": "addy.handoff",
  "timestamp": "2026-11-20T15:42:10.000Z",
  "data": {
    "contact": "919876543210",
    "contactId": "6740a0f2e4b0a1b2c3d4e5a1",
    "whatsapp": "68a06be5ea4b520115654c7",
    "status": "handed_off",
    "summary": "Runs 3 salons in Pune; wants appointment reminders on WhatsApp.",
    "learned": { "business_type": "Salon", "team_size": "3" },
    "lead": { "score": 74, "temperature": "hot", "stage": "qualified", "reason": "Clear need, budget fits, wants to start this month." },
    "handoff": { "reason": "Asked to speak to someone about a custom price", "summary": "Wants a discount for 3 branches; ready to pay this week.", "at": "2026-11-20T15:42:09.000Z" },
    "booked": false,
    "order": null,
    "replies": 9,
    "outOfHours": false,
    "teamBackAt": null
  }
}
```

| Extra field | Meaning |
| - | - |
| `outOfHours` | `true` when it happened outside your working hours. Addy told the customer when the team is back, and keeps the chat until then. |
| `teamBackAt` | When it's out of hours: when your team is back, as text, for example `tomorrow at 10:00 am`. |

To reply as a person from your CRM, send messages with [Send Message](https://docs.adsera.in/api-reference/msg/msg.md). The chat is already with your team, so Addy stays quiet. When you're done, [hand it back](https://docs.adsera.in/api-reference/addy/handback.md).

## addy.lead\_updated

A lead's stage or temperature changed: for example `warm` → `hot`, or `qualified` → `booked`. It isn't sent when only the score moves within the same temperature and stage, so you get the changes that matter, not every message.

```json theme={null}
{
  "event": "addy.lead_updated",
  "timestamp": "2026-11-20T15:30:02.000Z",
  "data": {
    "contact": "919876543210",
    "status": "active",
    "summary": "Runs 3 salons in Pune; wants appointment reminders on WhatsApp.",
    "lead": { "score": 82, "temperature": "hot", "stage": "booked", "reason": "Booked a demo for Friday 11 am.", "updatedAt": "2026-11-20T15:30:01.000Z" },
    "booked": true
  }
}
```

Use it to create or update the lead in your CRM: set its rating from `lead.temperature`, its status from `lead.stage`, and save `summary` as a note. Missed some while your server was down? [List Addy's Leads](https://docs.adsera.in/api-reference/addy/leads.md) with `updatedSince` catches up.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.