> ## 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 API

> Work with Addy, AdsEra's AI WhatsApp agent, from your own CRM: see what it learned, take chats over, tell it what happened, and get its leads.

Addy is AdsEra's AI agent. It answers your customers on WhatsApp, asks your qualifying questions, scores every lead, books meetings and takes orders. You set it up once in [**AI Agent**](https://app.adsera.in/dashboard/ai-agent).

With the Addy API, your own CRM or backend can:

| You want to | Use |
| - | - |
| See what Addy knows about a customer: chat summary, their answers, lead score, and who is replying | [Get a Customer's Addy Chat](https://docs.adsera.in/api-reference/addy/chat.md) |
| Let your salesperson take over a chat, so Addy stops replying | [Take a Chat from Addy](https://docs.adsera.in/api-reference/addy/take.md) |
| Let Addy answer again | [Hand a Chat Back to Addy](https://docs.adsera.in/api-reference/addy/handback.md) |
| Tell Addy something happened (order shipped, payment received) so it tells the customer | [Send an Event to Addy](https://docs.adsera.in/api-reference/addy/events.md) |
| Pull Addy's best leads into your CRM | [List Addy's Leads](https://docs.adsera.in/api-reference/addy/leads.md) |
| Be told the moment Addy hands a chat to a person, or a lead turns hot | Webhooks [`addy.handoff`](https://docs.adsera.in/api-reference/webhooks/addy#addy-handoff) and [`addy.lead_updated`](https://docs.adsera.in/api-reference/webhooks/addy#addy-lead-updated) |

> [!NOTE]
>
> This is **Addy**, AdsEra's own AI agent. The [Meta Business AI](https://docs.adsera.in/api-reference/business-agent/event.md) endpoints are for Meta's agent, which some businesses switch on in WhatsApp Manager instead. If you use Addy, you don't need them.

## Authentication

The same API key as the rest of the API: create one in [**Settings → API Keys**](https://app.adsera.in/setting/api-keys) and send both headers.

```http theme={null}
x-api-key: YOUR_APP_ID
x-api-secret: YOUR_APP_SECRET
```

Customers are found by **phone number with the country code**, for example `919876543210`. Spaces, `+` and dashes are ignored. If you have several WhatsApp numbers, AdsEra uses the one Addy last talked to that customer on. Send `whatsapp` (a number id from [List WhatsApp Numbers](https://docs.adsera.in/api-reference/whatsapp/list.md)) to choose one.

## A typical setup

**1. Get leads as Addy finds them**

Subscribe to the `addy.lead_updated` webhook in [Settings → Webhooks](https://app.adsera.in/setting/webhooks). Each time Addy moves a lead to a new stage or temperature, your CRM gets the score, the reason and the chat summary. To catch up, call [List Addy's Leads](https://docs.adsera.in/api-reference/addy/leads.md) with `updatedSince`.

**2. Alert your team when Addy needs a person**

Subscribe to `addy.handoff`. It arrives when a customer asks for a human, or when Addy can't help. It has Addy's summary, so your salesperson knows the context before replying.

**3. Take over and hand back from your CRM**

When your salesperson starts replying, call [Take a Chat from Addy](https://docs.adsera.in/api-reference/addy/take.md). When they're done, call [Hand a Chat Back to Addy](https://docs.adsera.in/api-reference/addy/handback.md). AdsEra also does this automatically: replying from the AdsEra inbox takes the chat, and Addy takes back chats that have been quiet for a while; you set how long in your AI Agent settings.

**4. Keep customers updated**

When an order ships or a payment comes in, call [Send an Event to Addy](https://docs.adsera.in/api-reference/addy/events.md). Addy tells the customer in its own words, using only the facts you send.

## Lead scores

Addy scores every customer from 0 to 100, from what they tell it, such as budget, need, timeline and whether they decide. The thresholds in your AI Agent settings turn the score into a **temperature**:

| Temperature | Meaning |
| - | - |
| `cold` | Little interest yet, or Addy doesn't know enough. |
| `warm` | Interested, with some buying signals. |
| `hot` | Ready to buy. Addy has already told your team, added the "Hot lead" label and created a task. |

The **stage** shows how far they got: `new` → `engaged` → `qualified` → `hot` → `booked` / `ordered` → `paid`, or `lost`.

The score, temperature and stage are also saved on the contact as `LEAD_SCORE`, `LEAD_TEMPERATURE` and `LEAD_STAGE`. So they also appear in [CRM contacts](https://docs.adsera.in/api-reference/crm/contacts/get.md).


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