Chatbot API

Integrate WAYSCloud chatbots into your applications.

Build AI-powered chatbots with your own knowledge sources, then access them programmatically from any backend, mobile app, or integration.

Quick start:

# List your chatbots
curl https://api.wayscloud.services/v1/chatbot/api/bots \
  -H "X-API-Key: wayscloud_api_xxx"

# Send a message
curl -X POST https://api.wayscloud.services/v1/chatbot/api/chat \
  -H "X-API-Key: wayscloud_api_xxx" \
  -H "Content-Type: application/json" \
  -d '{"bot_id": "my-bot", "message": "What are your prices?"}'

Streaming: Use /v1/chatbot/api/chat/stream for real-time token-by-token responses via Server-Sent Events.

Sessions: Omit session_id to start a new conversation. Include it to continue an existing one.

Authentication: API key with chatbot permission, sent via X-API-Key header.

Manage chatbots: Create and configure chatbots, add knowledge sources, and customize behavior in the WAYSCloud Dashboard.

Endpoints

Method	Path	Description
GET	/v1/chatbot/api/bots	List chatbots
POST	/v1/chatbot/api/chat	Send a message
POST	/v1/chatbot/api/chat/stream	Send a message (streaming)

GET /v1/chatbot/api/bots

List chatbots

Returns all active chatbots owned by the authenticated customer. Use the id or slug from this response as the bot_id parameter when calling the chat endpoints.

Response:

Field	Type	Description
bots	array	Active chatbots for this customer.

Example:

curl https://api.wayscloud.services/v1/chatbot/api/bots \
  -H "X-API-Key: YOUR_API_KEY"

---

POST /v1/chatbot/api/chat

Send a message

Send a message to a chatbot and receive a generated response based on the configured knowledge sources. The response includes the answer, relevant source citations, and usage metadata.

Request Body:

Field	Type	Description
bot_id	string	Required. Chatbot identifier. Accepts either the UUID or the slug (e.g. support-bot).
message	string	Required. The message to send to the chatbot.
session_id	string	Optional session identifier to continue an existing conversation. If omitted, a new session is created automatically. Reuse the returned session_id in subsequent requests to maintain conversation context.

Example:

{
  "bot_id": "support-bot",
  "message": "What are your prices?"
}

Response:

Field	Type	Description
session_id	string	Required. Session identifier. Reuse this in subsequent requests to continue the same conversation.
message_id	string	Required. Unique identifier for this response.
response	string	Required. Generated reply from the chatbot based on its knowledge sources.
citations	array	Sources referenced in the response, when available. May be empty if the answer was generated without specific source matches.
tokens_input	integer	Number of input tokens consumed.
tokens_output	integer	Number of output tokens generated.
response_time_ms	integer	Total processing time in milliseconds.

Example:

curl -X POST https://api.wayscloud.services/v1/chatbot/api/chat \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{...}'

---

POST /v1/chatbot/api/chat/stream

Send a message (streaming)

Send a message and receive a real-time streaming response via Server-Sent Events (SSE). Tokens are delivered incrementally as they are generated.

The first event is always meta, followed by zero or more token events, and finally done. If an error occurs during generation, an error event is sent instead of done.

Event types:

Type	Description
meta	Sent once at the start. Contains session ID and source citations.
token	Sent for each generated token.
done	Sent when generation is complete.
error	Sent if an error occurs. Contains a human-readable message.

Example stream:

data: {"type":"meta","data":{"session_id":"a1b2...","citations":[{"title":"Pricing","url":"https://example.com/pricing"}]}}
data: {"type":"token","content":"Our"}
data: {"type":"token","content":" prices"}
data: {"type":"token","content":" start"}
data: {"type":"token","content":" from"}
data: {"type":"done"}

Error example:

data: {"type":"error","content":"Service temporarily unavailable"}

Request Body:

Field	Type	Description
bot_id	string	Required. Chatbot identifier. Accepts either the UUID or the slug.
message	string	Required. The message to send to the chatbot.
session_id	string	Optional session identifier to continue an existing conversation. Reuse the session_id from a previous response to maintain context.

Example:

{
  "bot_id": "support-bot",
  "message": "Tell me about your services"
}

Example:

curl -X POST https://api.wayscloud.services/v1/chatbot/api/chat/stream \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{...}'

---