Skip to main content

Boltic AI Agent

Boltic AI Agent​

Purpose: Enable conversations with the Boltic AI Agent. When a user sends a message, the API ensures the correct user and conversation are used (or created if missing) and returns the AI Agent’s reply.

How it Works​

  • If a conversation ID is provided, the message continues in that conversation.
  • If no conversation ID is given, a new one will be created.
  • If a user ID or host ID is provided, the system validates and reuses the user.
  • If no user exists, one is created (requires a host ID and either an email or phone number).
  • The user’s message is then sent to the AI Agent, which generates a reply.

Parameters​

  • body.user: { id?, hostId?, email?, phone?, name?, additionalFields? }
    • Identifies the user. Requires hostId and at least one of email or phone when creating.
  • body.conversation: { id?, title? }
    • Identifies the conversation. If id is omitted, a new conversation is created.
  • body.surface: "web" | "hosted-web" | "call" | "whatsapp" | string
    • Channel where the conversation is happening.
  • body.query: string
    • The user’s actual message.
  • body.conversationContext: object (optional)
    • Extra context to guide the AI Agent’s responses, sent as key–value pairs.

Behavior​

  • Reuses existing users and conversations if IDs are provided and valid.
  • Creates new users if host ID and contact info are provided.
  • Creates new conversations when no conversation.id is supplied.
  • Sends the user message, waits for the AI Agent’s reply, and returns the response.

Returns​

{
  "user": { "id": "usr_123" },
  "conversation": { "id": "conv_456" },
  "message": {
    "id": "msg_789",
    "message": "Here’s the answer to your question.",
    "components": []
  }
}

Errors​

  • NotFound: User or conversation does not exist.
  • BadRequest: User/conversation mismatch or missing required fields.

Example Request​

{
  "user": { "hostId": "cust_123", "email": "[email protected]", "name": "Alice" },
  "conversation": { "title": "Order Help" },
  "surface": "web",
  "query": "Where is my order?",
  "conversationContext": { "locale": "en-US" }
}

Example Response​

{
  "user": { "id": "usr_abc" },
  "conversation": { "id": "thr_xyz" },
  "message": {
    "id": "msg_123",
    "message": "Your order is scheduled for delivery tomorrow.",
    "components": []
  }
}