Chat

toothfairyai@latest…

Manager for chat and message operations.

This manager provides methods to create, update, and manage chat conversations, as well as send messages to AI agents.

Example:

>>> client = ToothFairyClient(api_key="...", workspace_id="...")
>>> chat = client.chat.create(name="Support Chat", customer_id="cust-123")
>>> response = client.chat.send_to_agent("Hello", "agent-id", chat_id=chat.id)

Accessed via client.chat.

Methods

Method	HTTP	Endpoint
`create`	POST	`POST /chat/create`
`update`	POST	`POST /chat/update`
`get`	GET	`GET /chat/get/{chat_id}`
`list`	GET	`GET /chat/list`
`delete`	DELETE	`DELETE /chat/delete/{chat_id}`
`create_message`	POST	`POST /chat_message/create`
`get_message`	GET	`GET /chat_message/get/{message_id}`
`update_message`	POST	`POST /chat_message/update`
`list_messages`	GET	`GET /chat_message/list`
`send_to_agent`	POST	`POST /agent`

create

Create a new chat.

def create(
    name: str = '',
    customer_id: str = '',
    customer_info: Optional[Dict[str, Any]] = None,
    primary_role: str = 'user',
    external_participant_id: str = '',
    channel_settings: Optional[Dict[str, str]] = None
) -> Chat

Endpoint: POST /chat/create · API service

Request fields

Field	Type	Required	Description
`id`	`string`	no	Unique identifier
`workspaceid`	`string`	yes	Unique workspace identifier (UUID v4)
`createdBy`	`string`	no	ID of the user who created this resource
`visibility`	`string`	yes	Chat visibility: public, private, widget, job, or incognito

The Python SDK accepts snake_case keyword arguments and converts them to the camelCase wire fields shown above.

Response fields

Field	Type	Description
`id`	`string`	Unique identifier for the chat session
`owner`	`string`	Owner of this resource
`name`	`string`	Human-readable name of the chat session
`description`	`string`	Optional description of the chat purpose
`status`	`object`	Current status of the resource
`workspaceID`	`string`	Unique workspace identifier (UUID v4)
`creationTime`	`integer`	Unix timestamp of chat creation
`createdBy`	`string`	User ID who created the chat
`updatedBy`	`string`	ID of the user who last updated this resource
`visibility`	`string`	Chat visibility level

Example

client.chat.create()

update

Update an existing chat.

def update(
    chat_id: str,
    name: Optional[str] = None,
    customer_id: Optional[str] = None,
    customer_info: Optional[Dict[str, Any]] = None,
    primary_role: Optional[str] = None,
    external_participant_id: Optional[str] = None,
    channel_settings: Optional[Dict[str, str]] = None
) -> Chat

Endpoint: POST /chat/update · API service

Request fields

Field	Type	Required	Description
`id`	`string`	yes	Unique identifier
`workspaceid`	`string`	no	Unique workspace identifier (UUID v4)
`createdBy`	`string`	no	ID of the user who created this resource
`visibility`	`string`	no	Chat visibility: public, private, widget, job, or incognito

The Python SDK accepts snake_case keyword arguments and converts them to the camelCase wire fields shown above.

Response

Returns the Chat object — fields documented in the create section above.

Example

client.chat.update(chat_id="agent-id")

get

Get a chat by ID.

def get(chat_id: str) -> Chat

Endpoint: GET /chat/get/{chat_id} · API service

Response fields

No fields.

Example

client.chat.get(chat_id="agent-id")

list

List all chats.

def list(
    limit: Optional[int] = None,
    offset: Optional[int] = None
) -> ListResponse

Endpoint: GET /chat/list · API service

Example

client.chat.list()

delete

Delete a chat.

def delete(chat_id: str) -> Dict[str, bool]

Endpoint: DELETE /chat/delete/{chat_id} · API service

Response fields

Field	Type	Description
`success`	`boolean`	Operation success status
`data`	`object`	Response data
`message`	`string`	Optional success message

Example

client.chat.delete(chat_id="agent-id")

create_message

Create a message in a chat.

def create_message(
    chat_id: str,
    text: str,
    role: str = 'user',
    user_id: str = '',
    images: Optional[List[str]] = None,
    audios: Optional[List[str]] = None,
    videos: Optional[List[str]] = None,
    files: Optional[List[str]] = None
) -> Message

Endpoint: POST /chat_message/create · API service

Request fields

Field	Type	Required	Description
`id`	`string`	no	Unique identifier
`workspaceid`	`string`	yes	Unique workspace identifier (UUID v4)
`role`	`string`	yes	Message author role: system, user, or assistant

The Python SDK accepts snake_case keyword arguments and converts them to the camelCase wire fields shown above.

Response fields

Field	Type	Description
`id`	`string`	Unique identifier for the chat message
`role`	`string`	Role of the message sender

Allowed: system, handoff, notification, continuation | | status | string | Current processing status of the message

Example

client.chat.create_message(chat_id="agent-id", text="…")

get_message

Get a message by ID.

def get_message(message_id: str) -> Message

Endpoint: GET /chat_message/get/{message_id} · API service

Response

Returns the ChatMessage object — fields documented in the create-message section above.

Example

client.chat.get_message(message_id="agent-id")

update_message

Update a message.

def update_message(
    message_id: str,
    text: Optional[str] = None,
    role: Optional[str] = None,
    user_id: Optional[str] = None,
    images: Optional[List[str]] = None,
    audios: Optional[List[str]] = None,
    videos: Optional[List[str]] = None,
    files: Optional[List[str]] = None
) -> Message

Endpoint: POST /chat_message/update · API service

Request fields

Field	Type	Required	Description
`id`	`string`	yes	Unique identifier
`workspaceid`	`string`	no	Unique workspace identifier (UUID v4)
`role`	`string`	no	Message author role: system, user, or assistant

The Python SDK accepts snake_case keyword arguments and converts them to the camelCase wire fields shown above.

Response

Returns the ChatMessage object — fields documented in the create-message section above.

Example

client.chat.update_message(message_id="agent-id")

list_messages

List messages in a chat.

def list_messages(
    chat_id: str,
    limit: Optional[int] = None,
    offset: Optional[int] = None
) -> ListResponse

Endpoint: GET /chat_message/list · API service

Example

client.chat.list_messages(chat_id="agent-id")

send_to_agent

Send a message to an AI agent.

def send_to_agent(
    message: str,
    agent_id: str,
    chat_id: Optional[str] = None,
    phone_number: Optional[str] = None,
    customer_id: Optional[str] = None,
    provider_id: Optional[str] = None,
    customer_info: Optional[Dict[str, Any]] = None,
    attachments: Optional[Attachments] = None
) -> AgentResponse

Endpoint: POST /agent · AI service

The SDK routes this call via its internal chatter endpoint alias; the canonical API operation is /agent.

Request fields

Field	Type	Required	Description
`workspaceid`	`string`	yes	Unique workspace identifier
`chatid`	`string`	no	Chat ID. Omit to create a new chat (a new ID is returned in the stream).
`agentid`	`string`	yes	Agent ID to handle the conversation
`messages`	`array<object>`	yes	Messages to send to the Agent
`chat_history`	`array<object>`	no	Provide conversation context from previous turns without persisting.
`base_image`	`string`	no	Base image key for vision-enabled agents. Used as visual context for the conversation. Upload via document API first.
`storeMessages`	`boolean`	no	Whether to persist the generated messages to the chat (camelCase; the backend reads `storeMessages`, not `store_messages`)
`nextMessageId`	`string`	no	Optional ID for the next message (for client-side correlation)
`external_channel_type`	`string`	no	Optional external channel type (e.g. whatsapp, sms, email) when the request originates from a channel
`email_metadata`	`object`	no	Optional email metadata (subject, from, to, etc.) when the request originates from email
`plannerAgent`	`string`	no	Optional planner/orchestrator agent ID for the conversation
`from_planner`	`boolean`	no	Whether this request is being made from a planner flow
`name`	`string`	no	Optional chat name (defaults to "New Chat" when creating a new chat)

The Python SDK accepts snake_case keyword arguments and converts them to the camelCase wire fields shown above.

Response fields

Field	Type	Description
`contents`	`object`	Chat response content
`workspaceid`	`string`	Workspace identifier associated with the Agent

Example

client.chat.send_to_agent(message="…", agent_id="agent-id")

Chat​

Methods​

create​

Request fields​

Response fields​

Example​

update​

Request fields​

Response​

Example​

get​

Response fields​

Example​

list​

Example​

delete​

Response fields​

Example​

create_message​

Request fields​

Response fields​

Example​

get_message​

Response​

Example​

update_message​

Request fields​

Response​

Example​

list_messages​

Example​

send_to_agent​

Request fields​

Response fields​

Example​

Chat

Methods

create

Request fields

Response fields

Example

update

Request fields

Response

Example

get

Response fields

Example

list

Example

delete

Response fields

Example

create_message

Request fields

Response fields

Example

get_message

Response

Example

update_message

Request fields

Response

Example

list_messages

Example

send_to_agent

Request fields

Response fields

Example