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

# Yellow.ai

> Create Oktivo leads from your Yellow.ai website chatbot and send call results back to Yellow.ai

# Yellow\.ai

Connect your Yellow\.ai bot from **Connecter > Yellow\.ai** in the Oktivo dashboard. The connector works in two directions.

> [!NOTE]
>
> Availability depends on your Oktivo plan. If you do not see the Yellow\.ai tile in **Connecter**, ask support to enable it.

## What you get

**Website chatbot to Oktivo lead.** When a visitor shares a phone number in your Yellow\.ai chatbot, Oktivo creates a lead (or updates the lead that already has that number) and saves the chat on it. Your team can then call the lead from Oktivo.

**Oktivo call result to Yellow\.ai.** After an Oktivo call finishes and has been analysed, Oktivo writes the contact and the call status onto the matching customer profile in Yellow\.ai.

## Before you start

* A Yellow\.ai bot, and a Yellow\.ai user who can open **Settings > API Keys**.
* An Oktivo account with the Yellow\.ai connector enabled.
* For chatbot leads: someone who can edit the bot flow in Yellow\.ai Studio.

## Connect your bot

**1. Get the API key from Yellow\.ai**

In Yellow\.ai, open **Settings > API Keys** and create or copy an API key for your bot.

> [!WARNING]
>
> Treat the key like a password. Do not paste it into chat, email, or a document.

**2. Find the bot ID and region host**

The **bot ID** identifies your bot, for example `x1234567890123`. The **region host** is the Yellow\.ai address for your region, for example `cloud.yellow.ai`. Type only the host name. A leading `https://` or a trailing `/` is removed for you.

**3. Connect in Oktivo**

Open **Connecter**, find **Yellow\.ai**, and click **Connect**. Enter the API key, the bot ID, and the region host. Oktivo checks them with Yellow\.ai before saving. The key is encrypted and is never shown again.

### If connecting fails

| Message | What it means | What to do |
| - | - | - |
| Enter your Yellow\.ai API key to connect | The key field is empty | Enter the key |
| Enter your Yellow\.ai bot id to connect | The bot ID field is empty | Enter the bot ID |
| The CRM rejected the configured credentials | Yellow\.ai refused the key. The key, the bot ID, or the region host is wrong | Check all three. The key must belong to that bot |
| Could not connect to the CRM | Oktivo could not reach Yellow\.ai, or the host is not valid | Check the region host and try again |
| This Yellow\.ai bot is already connected to another account | Another Oktivo account uses this bot | Disconnect it there first, or contact support |

## Settings

After connecting, click **Settings** on the Yellow\.ai card. Your choices are saved and shown again when you reopen the panel.

| Setting | On by default | What it does |
| - | - | - |
| **Sync contact** | Yes | After a call is analysed, creates the contact in Yellow\.ai with the lead's name, phone, and email. It creates a new Yellow\.ai user each time, it does not look for an existing one |
| **Log call activity** | Yes | **Not active yet.** The switch is there, but Oktivo does not write a call summary to Yellow\.ai today. Turning it on or off changes nothing |
| **Update lead status** | Yes | Writes the call outcome (`done` or `failed`) to a field called `oktivo_lead_status` on the Yellow\.ai profile. It is the call outcome, not the lead stage in Oktivo. The field must exist in your Yellow\.ai customer data, otherwise Yellow\.ai ignores the value without showing an error |
| **Create leads from chatbot** | No | Turns on lead capture from your chatbot. You need a secret first (see below) |
| **Outbound notifications** | No | **Coming soon.** Cannot be turned on yet |

Pulling your existing Yellow\.ai contacts into Oktivo is also **not available yet**.

> [!NOTE]
>
> Only a finished, analysed call sends data to Yellow\.ai. Changing a lead's status by hand in Oktivo does not.

## Create leads from your chatbot

**1. Generate a secret**

In the Yellow\.ai settings, click **Generate secret**. Oktivo shows it once. Copy it and keep it somewhere safe.

> [!WARNING]
>
> If you click **Generate secret** again to replace it, the old secret stops working immediately. Update the Yellow\.ai API node straight away or new chats will be rejected.

**2. Turn on Create leads from chatbot**

The switch stays off until a secret exists.

**3. Add an API node in Yellow\.ai Studio**

Add an **API node** right after the step where the bot collects the visitor's phone number, and set it up as shown below.

### API node settings

The settings panel in Oktivo shows the exact URL and a ready-to-copy example. Use those values.

| Setting | Value |
| - | - |
| Method | `POST` |
| URL | `https://<your Oktivo backend address>/api/v2/connecter/webhooks/yellowai` |
| Header `Content-Type` | `application/json` |
| Header `x-yellow-bot-id` | Your bot ID |
| Header `x-oktivo-secret` | The secret you copied |
| Timeout | 15 seconds |
| Retry | On server errors (5xx), once or twice. A retry never creates a second lead |

### Body

```json theme={null}
{
  "name": "{{{name}}}",
  "phone": "{{{phone}}}",
  "email": "{{{email}}}",
  "conversationId": "{{{conversation_id}}}",
  "userId": "{{{yellow_user_id}}}",
  "pageUrl": "{{{page_url}}}",
  "summary": "{{{chat_summary}}}",
  "transcript": [
    { "role": "bot",  "text": "Hi! How can I help?",          "at": "2026-11-17T06:10:58Z" },
    { "role": "user", "text": "What does the Pro plan cost?", "at": "2026-11-17T06:11:10Z" }
  ]
}
```

> [!WARNING]
>
> The `{{{...}}}` names are examples. Variable names differ from bot to bot, so replace each one with the matching variable from your own flow. Remove any field your flow cannot supply.

| Field | Needed | Notes |
| - | - | - |
| `phone` | Yes | Include the country code (for example `+14155550123`) for numbers outside India. A plain 10-digit number is treated as an Indian number (`+91`) |
| `name` | No | Without it the lead is named `Contact` plus the last 4 digits. A later chat that includes a name replaces that placeholder |
| `email` | No | An invalid email is ignored. An email that already belongs to another lead is not saved |
| `conversationId` | Recommended | Lets Oktivo recognise the same chat if it is sent again. The chat is then updated, not added twice |
| `userId` | No | The Yellow\.ai user ID. If you send no `transcript`, Oktivo tries to fetch the chat from Yellow\.ai itself |
| `pageUrl` | No | The page the visitor was on |
| `summary` | No | A short summary, up to 500 characters |
| `transcript` | No | The chat, as a list of messages or one text. The whole chat is saved, up to 5,000 messages. Chats beyond that are saved up to the limit and marked as shortened |
| `profile` | No | Extra Yellow\.ai user details as a flat object, for example `"profile": {"city": "Pune", "language": "en"}`. Saved on the lead as the **Yellow\.ai profile**. Passwords, tokens and keys are never saved |

Send the `transcript` or a `summary` if your flow can. For long chats, send `userId` and leave out the `transcript`: Oktivo then fetches the whole chat from Yellow\.ai itself. Fetching with `userId` has not been confirmed against a live bot, so it may not work for every setup. If it fails, the lead is still created and keeps the summary.

> [!WARNING]
>
> Oktivo accepts a request body of up to 100 KB. A very long `transcript` sent in the request can be larger than that and is refused, and the lead is not created. For long chats, send `userId` instead of the `transcript`.

### What is saved from Yellow\.ai

* **The full chat.** Every message, in order, with who wrote it (visitor, bot or agent) and the time. Sending the same chat again changes nothing. Sending a longer version of the same chat adds the new messages. A shorter, older copy is ignored.
* **Profile details.** Details such as name, email, city and country are copied to the lead only where the lead has nothing better yet. An existing name, email or location is never overwritten. Everything else (language, time zone, last channel and your own Yellow\.ai properties) is kept in the **Yellow\.ai profile** card on the lead. If you turned off pulling name or email in your field mapping, those two are not copied, but they still show in the profile card.
* **Optional profile lookup.** Oktivo can also look up the profile from Yellow\.ai with `userId`. This is switched off by default because it has not been confirmed against a live bot. Ask your administrator if you want it enabled.

### Test it

Ask a developer to send this request with your own values, or use the example in the settings panel:

```bash theme={null}
curl -X POST 'https://<your Oktivo backend address>/api/v2/connecter/webhooks/yellowai' \
  -H 'Content-Type: application/json' \
  -H 'x-yellow-bot-id: <your bot id>' \
  -H 'x-oktivo-secret: YOUR_SECRET' \
  -d '{"name":"Test Visitor","phone":"+91 90000 00001","conversationId":"conv_test_1","summary":"Test chat"}'
```

The first call creates a lead. Sending the same request again changes nothing, and you still have one lead.

## How leads appear in Oktivo

* The lead's **channel** is **Yellow\.ai** and its **source** is **Website chatbot**. You can filter on both in the lead list.
* Your bot ID is saved on the lead.
* The chat is saved as one entry in the lead's conversation timeline, counted under **Notes**. The entry shows the last few messages. Click **View full chat** to read the whole conversation as a scrollable chat with visitor, bot and agent bubbles and times. Long chats load 100 messages at a time as you scroll, with **Load more**, **Jump to latest** and **Load older** buttons.
* If a chat was very long, a banner tells you that only part was saved. If it is still being copied from Yellow\.ai, the banner says it is still syncing. If the copy stopped early, it says **Partially synced** and finishes the next time Yellow\.ai sends the same chat.
* A collapsible **Yellow\.ai profile** card (in the **Marketing** section of the lead) lists the details Yellow\.ai had for the visitor. It is hidden when there are none.
* Deleting the lead also deletes its saved chat.
* If the phone number already belongs to a lead (added by hand, imported, or from another connector), that lead is updated instead of duplicated. It keeps its original channel. The chatbot visit is added to its history.
* If the same visitor chats again with a different conversation, the new chat is added as another entry.

## Sync activity

Click **Sync activity** on the Yellow\.ai card to see recent activity, newest first. You will see one row for each lead created or updated from the chatbot, and one for each push after a call. Rows marked **skipped** were not processed on purpose, for example because a setting was off, the phone number was missing, or the chat could not be fetched. Rows marked **failed** include the reason.

## Troubleshooting

| Symptom | Likely cause | Fix |
| - | - | - |
| The API node gets **401** | The secret is wrong, was replaced, or was never generated | Generate a secret, copy it, and paste it into the `x-oktivo-secret` header |
| **422** `NO_PHONE` | The phone field is empty | Check that the phone variable is filled in before the API node runs |
| **422** `INVALID_PHONE` | The value is not a valid phone number | Send digits with a country code, for example `+14155550123` |
| The call succeeds but no lead appears | The bot ID in `x-yellow-bot-id` does not match the connected bot, or **Create leads from chatbot** is off | Use the exact bot ID you connected, and turn the switch on |
| The lead's name is `Contact 3210` | The flow did not send a name | Add `name` to the body. A later chat with a name fixes the lead |
| The lead has no chat, only a summary | No `transcript` was sent and Oktivo could not fetch the chat | Send `transcript` or `summary` in the body |
| The chat stops before the end | The chat was sent when the phone was shared, and the visitor kept talking | Add a second API node at the end of the chat with the same `conversationId` and the full `transcript` (or the same `userId`) |
| The API node gets **413** | The request body is over 100 KB, usually a very long `transcript` | Send `userId` and leave out the `transcript` so Oktivo fetches the chat itself |
| The chat says **Partially synced** | Yellow\.ai was asked for too many pages in a minute, or it was slow | Wait, or let the API node send the same chat again. It continues where it stopped |
| Two chats show as one | No `conversationId` was sent | Send `conversationId` |
| Status in Yellow\.ai is not updated | The `oktivo_lead_status` field does not exist in Yellow\.ai, or Sync contact did not run | Add the field in Yellow\.ai and check **Sync activity** |
| **503** from Oktivo | Too many requests for this bot (more than 120 per minute), or a short wait | Let the API node retry |

> [!NOTE]
>
> A phone number without a country code is treated as Indian (`+91`). For visitors in other countries, make your flow add the country code before it sends the number.

## FAQ

> [accordion] Does it copy my whole Yellow\.ai contact list into Oktivo?
>
> No. It only creates a lead when your bot flow sends one, which is when a visitor shares a phone number. Importing existing Yellow\.ai contacts is not available yet.

> [accordion] What happens if the same visitor is sent twice?
>
> Nothing is duplicated. The same delivery is recognised and ignored. A repeat visit with the same phone number updates the existing lead.

> [accordion] Will a lead be created without a phone number?
>
> No. A request without a valid phone number is refused and no lead is created.

> [accordion] Why does Log call activity do nothing?
>
> Oktivo does not write call summaries to Yellow\.ai yet. The switch is a placeholder until that is available.

> [accordion] Does changing a lead's status in Oktivo update Yellow\.ai?
>
> No. Only a finished, analysed call sends data to Yellow\.ai, and what it sends is the call outcome.

> [accordion] Can I use the same bot in two Oktivo accounts?
>
> No. A bot can be connected to one Oktivo account at a time.

> [accordion] What happens if I disconnect?
>
> Syncing stops and your Yellow\.ai settings and secret are removed. If you reconnect later, you start with the default settings and generate a new secret.

> [accordion] Where is my API key stored?
>
> It is encrypted and never shown again. To change it, connect again with the new key. Your settings are kept when you reconnect without disconnecting first.

## Related

> [card] [Lead Capture](https://stage-docs.oktivo.com/guides/lead-capture.md)
>
> Other ways to bring leads into Oktivo

> [card] [CRM Integration Guide](https://stage-docs.oktivo.com/guides/crm-integration.md)
>
> Generic CRM setup with code samples


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