Sending Chats

Initiating a chat

To initiate a chat session, send the chat message content in a POST request to the /api/chat endpoint, along with the id of the agent that will be answering your prompt. User's chat messages can have up to 2000 characters.

fetch('http://localhost:3000/api/chat', {
	method: "POST",
	headers: {
		'X-API-KEY': '',
		'X-Organization-Id': ''
	},
	body: JSON.stringify({
		agentId: "",
		message: {
			content: "chat prompt from user"
		},
	})
})

A chat session will apply the access controls associated with the agent. Consequently, the responses users receive within the chat session can include any document the agent has access to. Note that agents must belong to a single organization, so these access controls will still be confined to the agent's organization.

Continuing a chat

To continue an existing chat, pass the id of the chat in the request body. Chat IDs are auto-generated after the initial API call, and added to the first line of the streaming response, in this format:

8:[{"chatId":"auto-generated-uuid"}]

You do not need to provide the agentId in subsequent messages within the same chat session. Use the chat id as follows:

fetch('http://localhost:3000/api/chat', {
	method: "POST",
	headers: {
		'X-API-KEY': 'your-api-key',
		'X-Organization-Id': 'organization id for impersonated user'
	},
	body: JSON.stringify({
		id: "existing-chat-session-id",
		message: {
			content: "Agent chat prompt"
		},
		metadata: {
			engagementId: "",
			responseId: ""
		}
	})
})

Impersonating a user

You may "impersonate" a user by passing an identifying field: either userId or email. If the "impersonatedUser" object is not provided, the chat will be created for the user associated with the signing API key.

fetch('http://localhost:3000/api/chat', {
	method: "POST",
	headers: {
		'X-API-KEY': 'your-api-key',
		'X-Organization-Id': 'organization id for impersonated user'
	},
	body: JSON.stringify({
		agentId: "",
		message: {
			content: "Agent chat prompt from user"
		},
		impersonatedUser: {
			//provide either id or email
			id: "",
			email: ""
		},
	})
})

When impersonating a user, you must ensure your organization id header is for an agent/organization that the impersonated user has access to.

If you are impersonating a user that doesn't yet exist in Caddie, you must impersonate them using an email address. Caddie will create a new user with that email, assigning them a random password, and will grant them access to the organization id and agent id specified in your request.

Metadata Filtering

The chat API endpoint supports arbitrary metadata to apply access controls and generate metadata filters. It can be used to apply your pre-existing access controls to the chat context. To make requests using custom metadata filtering, see the documentation for Custom Metadata Filtering. Using metadata filtering requires following the configuration steps outlined in that section of the Caddie documentation.

To use metadata filtering during chats, a metadata object can be added to your request:

fetch('http://localhost:3000/api/chat', {
	method: "POST",
	headers: {
		'X-API-KEY': '',
		'X-Organization-Id': ''
	},
	body: JSON.stringify({
		agentId: '',
		message: {
			content: "Agent chat prompt"
		},
		metadata: { field1: '', field2: '' }
	})
})