Attach a lead to a conversation

Attach or update a lead for a specific conversation. This endpoint allows you to associate customer information with a conversation.

UUID immutability: Once a lead exists, its uuid can never be changed. Attempting to change an existing lead's uuid returns a 400 error.

Behavior:

• If the conversation already has a lead attached, that lead is updated with the provided fields (its uuid cannot be changed).
• If no lead is attached, the system searches for an existing lead using ALL provided identifiers together in a single query (best-effort matching).
• If an existing lead is found, it is updated and attached to the conversation (its uuid cannot be changed).
• If no lead is found, a new lead is created with the provided information and attached to the conversation.

Search strategy: Best-effort matching using all provided fields in a single query. For example, if you provide both email and phone, the system will search for a lead that matches BOTH values, not just email OR phone.

Name matching: Names are compared with an exact, case-sensitive string match. If several leads match the provided fields (for example, two leads share the same name), one of them is used, and which one is not guaranteed. For deterministic matching, use unique identifiers (email, phone, leadId, etc.).

Creating new leads: To create a new lead, provide at least one field besides leadId (name, email, phone, psid, ig_username, username, or info); info must come with another lead field. UUID alone is not sufficient for creation.

UUID handling: Pass a lead's uuid as leadId. When creating a new lead, the provided leadId becomes its uuid; otherwise a new UUID is generated. A uuid must be unique within the chatbot; creating a lead with a uuid that is already in use returns a 400 error.

Example body, updating an existing lead found by email:

{  "chatbotId": "6650f1c2a9e4b83d2c7a1f05",  "conversationId": "3f2b8c1e-9a4d-4e7b-8c2a-5d1e6f7a8b9c",  "email": "[email protected]",  "phone": "+14155550123"}

Example body, creating a lead with a specific leadId:

{  "chatbotId": "6650f1c2a9e4b83d2c7a1f05",  "conversationId": "3f2b8c1e-9a4d-4e7b-8c2a-5d1e6f7a8b9c",  "leadId": "8d0c2b6e-4f1a-4b7c-9e3d-2a5f6b7c8d9e",  "name": "Jane Doe",  "email": "[email protected]"}