Documentation/API Reference

Public API Reference

Chat with your agents, read and export conversations, and manage agents, sources and end-user profiles from your own systems.

Base URL
https://api.sellwhisperai.com/v1
Authentication
Authorization: Bearer sk-...
Format
JSON, chat streams as SSE
Download the OpenAPI document

Authentication

Create an API key under Settings → API Keys and send it as a Bearer token. Every call is scoped to the key's account: you can never read or change another account's data. Keep keys on your server; never put them in a browser or app. The Public API needs the Starter plan or above.

curl https://api.sellwhisperai.com/v1/conversations \
  -H "Authorization: Bearer $SELLWHISPER_API_KEY"

Streaming chat

POST /v1/agents/{agent_id}/chat streams the reply as server-sent events while the agent writes it: one conversation event, token events with pieces of the reply as the model generates them, then done with the full reply. Pass user_id, your own id for the end user, so you can list or delete their conversations later.

Tokens are a live preview. Append each token to what you show, and clear it on reset: the text before a reset is not the reply. A reset comes when the agent looks something up after it started writing (the answer streams again after the lookup), or when the reply is rewritten after the model wrote it, for example when your agent's UTM parameters are added to its links.

The token text after the last reset always equals done.text, the reply stored in the conversation, so you can also simply replace the preview with done.text. A reply the agent sends without the model (an over-limit notice, a queue position) arrives as one token. If the reply fails after the stream started, the stream ends with an error event ({"detail": "..."}) instead of done; your message is kept.

curl -N https://api.sellwhisperai.com/v1/agents/AGENT_ID/chat \
  -H "Authorization: Bearer $SELLWHISPER_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"message": "Where is my order?", "user_id": "user_123"}'

The stream

event: conversation
data: {"conversation_id": "c0a8..."}

event: token
data: {"text": "Let me check. "}

event: reset
data: {}

event: token
data: {"text": "Your order "}

event: token
data: {"text": "shipped yesterday."}

event: done
data: {"conversation_id": "c0a8...", "message_id": "9f1e...", "text": "Your order shipped yesterday.", "outcome": "replied"}

Node.js

// Node 18+
const res = await fetch("https://api.sellwhisperai.com/v1/agents/" + AGENT_ID + "/chat", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${process.env.SELLWHISPER_API_KEY}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({ message: "Where is my order?", user_id: "user_123" }),
});
if (!res.ok) throw new Error(`${res.status} ${await res.text()}`);

const render = (text) => console.clear() || console.log(text); // your chat bubble

const decoder = new TextDecoder();
let buffer = "";
let reply = ""; // what to show while the agent writes
for await (const chunk of res.body) {
  buffer += decoder.decode(chunk, { stream: true });
  let end;
  while ((end = buffer.indexOf("\n\n")) !== -1) {
    const raw = buffer.slice(0, end);
    buffer = buffer.slice(end + 2);
    const event = raw.match(/^event: (.*)$/m)?.[1];
    const data = JSON.parse(raw.match(/^data: (.*)$/m)?.[1] ?? "{}");
    if (event === "token") reply += data.text;
    if (event === "reset") reply = "";
    if (event === "done") reply = data.text; // the stored reply
    if (event === "error") throw new Error(data.detail);
    render(reply);
  }
}

Python

import json
import os

import httpx

url = f"https://api.sellwhisperai.com/v1/agents/{AGENT_ID}/chat"
headers = {"Authorization": f"Bearer {os.environ['SELLWHISPER_API_KEY']}"}
body = {"message": "Where is my order?", "user_id": "user_123"}

with httpx.stream("POST", url, headers=headers, json=body, timeout=60) as res:
    res.raise_for_status()
    event, reply = None, ""
    for line in res.iter_lines():
        if line.startswith("event: "):
            event = line[len("event: "):]
        elif line.startswith("data: "):
            data = json.loads(line[len("data: "):])
            if event == "token":
                reply += data["text"]
            elif event == "reset":
                reply = ""
            elif event == "done":
                reply = data["text"]  # the stored reply
                print(reply, data["outcome"], data["conversation_id"])
            elif event == "error":
                raise RuntimeError(data["detail"])

To continue the conversation, send its conversation_id. Set "stream": false to get the done payload as plain JSON instead. outcome is replied, new_conversation (a new conversation was started; use the returned conversation_id from now on), over_limit, paused (your team paused the conversation; the message is kept), escalated (forwarded to the human handling it) or queued (waiting for a human). text is empty when nothing is sent back.

curl https://api.sellwhisperai.com/v1/agents/AGENT_ID/chat \
  -H "Authorization: Bearer $SELLWHISPER_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"message": "And when will it arrive?", "conversation_id": "c0a8...", "stream": false}'

Errors and rate limits

401The API key is missing, wrong or revoked.
402The account's plan doesn't include the Public API (limit_type feature_public_api). It needs Starter or above.
404The agent, conversation, source or profile doesn't exist in this key's account.
409The request conflicts with what exists, e.g. a profile for that user_id already exists.
422The request body or query failed validation; detail says which field and why.
429The key's rate limit was exceeded. Wait for Retry-After seconds.

Each API key may make 60 requests per minute. Over the limit you get 429 with a Retry-After header in seconds; back off for that long and retry.

HTTP/1.1 429 Too Many Requests
Retry-After: 42
X-RateLimit-Limit: 60
X-RateLimit-Remaining: 0
X-RateLimit-Reset: 42

{"detail": {"error": "rate_limited", "message": "Rate limit exceeded for this API key.", "retry_after": 42}}

Chat

Chat with an agent

POST/v1/agents/{agent_id}/chat

Send the end user's message and get the agent's reply. By default the reply streams as server-sent events while the model writes it: conversation (the conversation_id), then token events (text pieces to append), possibly reset (clear what you appended: that text was not the reply), then done (the full response below; its text is the stored reply and always equals the tokens since the last reset). With "stream": false the response is that JSON instead. Pass the returned conversation_id to continue the conversation.

Parameters

NameInTypeDescription
agent_id *pathstring

Request body (application/json)

NameTypeDescription
message *string
conversation_idstringContinue this conversation; omit to start a new one.
user_idstringThe end user's id in your system, for a new conversation. Lets you list or delete that end user's conversations later.
streambooleanStream the reply as server-sent events, token by token as the model generates it.

Responses

  • 200 Successful Response ChatResponse (application/json or text/event-stream)

Conversations

List conversations

GET/v1/conversations

The account's conversations, newest first, filtered by agent, end user, search text and start time.

Parameters

NameInTypeDescription
pagequeryinteger
per_pagequeryinteger
agent_idquerystring
user_idquerystringThe end user's id in your system.
qquerystringSearch message text and end-user name/email.
created_afterquerydatetimeConversations started at or after this time (UTC if no offset).
created_beforequerydatetimeConversations started before this time (UTC if no offset).

Responses

Delete an end user's conversations

DELETE/v1/conversations

Delete every conversation of one end user, e.g. for a deletion request. Conversations without that user_id are never touched.

Parameters

NameInTypeDescription
user_id *querystringThe end user's id in your system.
agent_idquerystringOnly this agent's conversations.

Responses

Export conversations

GET/v1/conversations/export

Matching conversations with their messages, newest conversation first, at most limit. CSV has one row per message.

Parameters

NameInTypeDescription
formatquery"json" | "csv"
limitqueryinteger
agent_idquerystring
user_idquerystringThe end user's id in your system.
qquerystringSearch message text and end-user name/email.
created_afterquerydatetimeConversations started at or after this time (UTC if no offset).
created_beforequerydatetimeConversations started before this time (UTC if no offset).

Responses

Rate an agent reply

POST/v1/conversations/{conversation_id}/messages/{message_id}/feedback

Thumbs up or down on one of the agent's replies, e.g. from your own chat UI. The latest rating is the message's feedback.

Parameters

NameInTypeDescription
conversation_id *pathstring
message_id *pathstring

Request body (application/json)

NameTypeDescription
feedback *"thumbs_up" | "thumbs_down"

Responses

Agents

Get an agent

GET/v1/agents/{agent_id}

The agent's settings.

Parameters

NameInTypeDescription
agent_id *pathstring

Responses

Update an agent

PATCH/v1/agents/{agent_id}

Change only the settings sent, with the Dashboard's validation.

Parameters

NameInTypeDescription
agent_id *pathstring

Request body (application/json)

NameTypeDescription
namestring
system_promptstring
tonestring
personalityobject
temperaturenumber
data_source_idstring
is_activeboolean
widget_configobject
model_providerstring
model_namestring
custom_domainstring
allowed_domainsstring[]
security_settingsAgentSecuritySettings
notification_preferencesobject
channel_instructionsobject
utm_parametersobject
answer_languagestring
monthly_conversation_capinteger
idle_auto_end_daysinteger
public_comment_repliesboolean

Responses

Sources

Create a source

POST/v1/agents/{agent_id}/sources

Add a text snippet, a Q&A (with optional question variations) or a website to crawl, chosen by type. Processing runs in the background: poll GET /v1/agents/{agent_id}/sources for its status.

Parameters

NameInTypeDescription
agent_id *pathstring

Request body (application/json)

One of: TextSourceCreate, QASourceCreate, WebsiteSourceCreate, chosen by type.

Responses

  • 201 Successful Response Source

List sources

GET/v1/agents/{agent_id}/sources

The agent's sources, newest first.

Parameters

NameInTypeDescription
agent_id *pathstring
limitqueryinteger

Responses

Delete a source

DELETE/v1/agents/{agent_id}/sources/{source_id}

Delete a source and everything learned from it.

Parameters

NameInTypeDescription
agent_id *pathstring
source_id *pathstring

Responses

  • 204 Successful Response

Upload a file source

POST/v1/agents/{agent_id}/sources/files

Upload a file (PDF, DOCX, TXT, MD, CSV, XLSX or PPTX; 50 MB at most).

Parameters

NameInTypeDescription
agent_id *pathstring

Request body (multipart/form-data)

NameTypeDescription
file *file

Responses

  • 201 Successful Response Source

Profiles

List profiles

GET/v1/profiles

The account's profiles, most recently seen first.

Parameters

NameInTypeDescription
searchquerystringMatch user id, email or name.
limitqueryinteger
offsetqueryinteger

Responses

Create a profile

POST/v1/profiles

Create the profile for user_id; 409 if it already exists (update it with PATCH /v1/profiles/{user_id}).

Request body (application/json)

NameTypeDescription
emailstring
namestring
attributesobject
user_id *string

Responses

Get a profile

GET/v1/profiles/{user_id}

The profile of the end user with this user_id.

Parameters

NameInTypeDescription
user_id *pathstring

Responses

Update a profile

PATCH/v1/profiles/{user_id}

Update email/name when given and the given attributes (null clears one); attributes not named are kept.

Parameters

NameInTypeDescription
user_id *pathstring

Request body (application/json)

NameTypeDescription
emailstring
namestring
attributesobject

Responses

Delete a profile

DELETE/v1/profiles/{user_id}

Delete the profile. Its conversations stay, unlinked (delete those with DELETE /v1/conversations?user_id=).

Parameters

NameInTypeDescription
user_id *pathstring

Responses

  • 204 Successful Response

Schemas

AgentResponse

NameTypeDescription
id *string
account_id *string
workspace_idstring
name *string
system_prompt *string
tone *string
personality *object
temperature *number
data_source_idstring
is_active *boolean
widget_config *object
model_provider *string
model_name *string
custom_domainstring
allowed_domainsstring[]
security_settingsAgentSecuritySettings
notification_preferencesobject
channel_instructionsobject
utm_parametersobject
answer_languagestring
monthly_conversation_capinteger
idle_auto_end_daysinteger
public_comment_repliesboolean
created_atdatetime
updated_atdatetime
last_trained_atdatetime

AgentSecuritySettings

NameTypeDescription
rate_limitRateLimitSettings
spam_detectionboolean
blocked_countriesstring[]

AgentUpdate

NameTypeDescription
namestring
system_promptstring
tonestring
personalityobject
temperaturenumber
data_source_idstring
is_activeboolean
widget_configobject
model_providerstring
model_namestring
custom_domainstring
allowed_domainsstring[]
security_settingsAgentSecuritySettings
notification_preferencesobject
channel_instructionsobject
utm_parametersobject
answer_languagestring
monthly_conversation_capinteger
idle_auto_end_daysinteger
public_comment_repliesboolean

ChatRequest

NameTypeDescription
message *string
conversation_idstringContinue this conversation; omit to start a new one.
user_idstringThe end user's id in your system, for a new conversation. Lets you list or delete that end user's conversations later.
streambooleanStream the reply as server-sent events, token by token as the model generates it.

ChatResponse

NameTypeDescription
conversation_id *string
message_idstring
text *string
outcome *stringreplied, new_conversation, over_limit, paused, escalated or queued

ConversationExport

NameTypeDescription
data *ExportedConversationOut[]

ConversationList

NameTypeDescription
data *ConversationOut[]
total *integer
page *integer
per_page *integer

ConversationOut

NameTypeDescription
id *string
agent_id *string
channel *string
status *string
user_idstring
customer_namestring
customer_emailstring
page_urlstring
created_at *datetime
updated_at *datetime

DeleteResponse

NameTypeDescription
deleted *integer

ExcludeRule

NameTypeDescription
type *ExcludeRuleType
value *string

ExcludeRuleType

See the OpenAPI document for this schema's values.

ExportedConversationOut

NameTypeDescription
id *string
agent_id *string
channel *string
status *string
user_idstring
customer_namestring
customer_emailstring
page_urlstring
created_at *datetime
updated_at *datetime
messages *MessageOut[]

FeedbackRequest

NameTypeDescription
feedback *"thumbs_up" | "thumbs_down"

FeedbackResponse

NameTypeDescription
message_id *string
feedback *"thumbs_up" | "thumbs_down"
created_at *datetime

MessageOut

NameTypeDescription
id *string
role *string
content *string
created_at *datetime
feedback"thumbs_up" | "thumbs_down"

ProfileCreate

NameTypeDescription
emailstring
namestring
attributesobject
user_id *string

ProfileFields

NameTypeDescription
emailstring
namestring
attributesobject

ProfileList

NameTypeDescription
data *ProfileOut[]
total *integer
limit *integer
offset *integer

ProfileOut

NameTypeDescription
user_id *string
emailstring
namestring
attributes *object
last_seen_atdatetime
created_at *datetime
updated_at *datetime

QASourceCreate

NameTypeDescription
type *"qa"
question *string
answer *string
variationsstring[]

RateLimitSettings

NameTypeDescription
messages *integer
window_seconds *integer

Source

NameTypeDescription
id *string
name *string
type *stringtext, qa, website, file, or another kind
status *stringprocessing, completed, failed, embedding_pending, ...
error_messagestring
created_at *datetime

SourceList

NameTypeDescription
data *Source[]

TextSourceCreate

NameTypeDescription
type *"text"
name *string
content *string

WebsiteSourceCreate

NameTypeDescription
url *string
namestring
scraping_strategystring
render_javascriptboolean
wait_for_selectorstring
wait_timeoutinteger
enable_crawlingboolean
max_pagesinteger
max_depthinteger
same_domain_onlyboolean
respect_robotsboolean
delay_between_requestsnumber
extract_tablesboolean
extract_metadataboolean
include_patternsstring[]
exclude_patternsstring[]
exclude_rulesExcludeRule[]
slow_crawlboolean
ignore_query_paramsboolean
cookie_headerstring
type *"website"

Webhooks

Add an endpoint under Settings → Webhooks (or on an agent's Webhooks page) and pick the events to receive. Each event is sent as a JSON POST with the event name in X-Webhook-Event.

POST https://your-server.example.com/webhooks/sellwhisper
Content-Type: application/json
X-Webhook-Event: conversation.created
X-Webhook-Signature: 5d41402abc4b2a76b9719d911017c592...

{"event": "conversation.created", "timestamp": "2026-11-10T09:30:00", "data": {...}}

Verifying signatures

Every delivery, including the dashboard's Test delivery, carries an X-Webhook-Signature header: the lowercase hex HMAC-SHA256 of the raw request body, keyed with your endpoint's signing secret. Reject any request whose signature doesn't match.

  1. Open the endpoint's menu and choose Signing secret to reveal and copy it. Store it as a secret on your server. Each endpoint has its own.
  2. Read the raw request body as bytes, before any JSON parsing. Re-serialized JSON will not match.
  3. Compute HMAC-SHA256 of those bytes with the secret and hex-encode it.
  4. Compare it to X-Webhook-Signature with a constant-time comparison. If they differ, respond 401 and ignore the payload.

Node.js (Express)

import crypto from "node:crypto";
import express from "express";

const app = express();
const secret = process.env.SELLWHISPER_WEBHOOK_SECRET;

// Keep the raw body: the signature covers the exact bytes we sent.
app.post("/webhooks/sellwhisper", express.raw({ type: "application/json" }), (req, res) => {
  const expected = crypto.createHmac("sha256", secret).update(req.body).digest("hex");
  const received = req.get("X-Webhook-Signature") ?? "";
  const valid =
    received.length === expected.length &&
    crypto.timingSafeEqual(Buffer.from(received), Buffer.from(expected));
  if (!valid) return res.status(401).end();

  const event = JSON.parse(req.body.toString("utf8"));
  // ... handle event.event / event.data
  res.status(200).end();
});

Python (FastAPI)

import hashlib
import hmac
import os

from fastapi import FastAPI, HTTPException, Request

app = FastAPI()
SECRET = os.environ["SELLWHISPER_WEBHOOK_SECRET"]


@app.post("/webhooks/sellwhisper")
async def sellwhisper_webhook(request: Request):
    raw = await request.body()  # the exact bytes we sent
    expected = hmac.new(SECRET.encode(), raw, hashlib.sha256).hexdigest()
    received = request.headers.get("X-Webhook-Signature", "")
    if not hmac.compare_digest(expected, received):
        raise HTTPException(status_code=401)
    event = await request.json()
    # ... handle event["event"] / event["data"]
    return {"ok": True}

Rotating the secret

Choose Rotate secret in the same dialog if a secret leaks. The old secret stops working immediately and every later delivery is signed with the new one, so update your server right after rotating.

Clients and SDKs

Generate a client

Feed the OpenAPI document to any generator, such as openapi-generator or openapi-typescript, to get a typed client for your language.

openapi.json

React Native / Mobile SDK

npm install @sellwhisper/chat-client @sellwhisper/react-native
React Native SDK docs

Need Help?

Check out our guides or reach out to our developer support team