Conversation Operations

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": "jane@chat-data.com",
  "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": "jane@chat-data.com"
}
post/attach-lead

Request

  • Base URL: https://api.chat-data.com/api/v2
  • URL: https://api.chat-data.com/api/v2/attach-lead
  • Auth: HTTP bearer

Request body

chatbotIdstring required

The unique identifier of the chatbot.

conversationIdstring required

The unique identifier of the conversation.

leadIdstring

Lead UUID. Can be used alone to find an existing lead, but is not sufficient for creating a new lead. Important: Once a lead exists, its uuid can never be changed. Attempting to change it returns a 400 error. When creating a new lead, this value becomes its uuid; otherwise a new UUID is generated.

namestring

Lead name. Can be used to find an existing lead with an exact, case-sensitive string match. If several leads share the same name, one of them is used, and which one is not guaranteed. Use unique identifiers for deterministic matching.

emailstring email

Lead email address. Must be a valid, deliverable email address of at most 254 characters (RFC 5321).

phonestring

Lead phone number. It must be a valid phone number in international format, starting with +.

psidstring

Page-scoped ID (typically for Facebook Messenger).

ig_usernamestring

Instagram username.

usernamestring

Slack or Telegram username. A platform-specific identifier, distinct from ig_username (Instagram) and psid (Messenger).

infostring

Additional information about the lead, up to 1,000,000 characters. It may be truncated to 1,000 tokens if "User Info Truncation" is turned on in Settings > Limits Control.

Example request

{
  "chatbotId": "6650f1c2a9e4b83d2c7a1f05",
  "conversationId": "3f2b8c1e-9a4d-4e7b-8c2a-5d1e6f7a8b9c",
  "name": "Jane Doe",
  "email": "jane@chat-data.com",
  "phone": "+14155550123",
  "info": "Interested in the annual plan; asked about SSO."
}

Response

Successful response.

status'success' required

Example response

{
  "lead": {
    "leadId": "8d0c2b6e-4f1a-4b7c-9e3d-2a5f6b7c8d9e",
    "name": "Jane Doe",
    "email": "jane@chat-data.com",
    "phone": "+14155550123",
    "info": "Interested in the annual plan; asked about SSO.",
    "source": "api"
  }
}

Changes

No recorded changes to this operation across all 1 revision of this API.