Skip to main content
POST
Process a message with an assistant

Authorizations

Authorization
string
header
required

An API key from your Devic console, sent as Authorization: Bearer <key>. An embedded front end sends a tenant-session token instead, so no API key reaches the browser, and an OAuth integration sends its access token. Missing, invalid or expired credentials get a 401. See Authentication.

Path Parameters

identifier
string
required

Identifier of the assistant, as returned by the assistants endpoints.

Query Parameters

async
boolean
default:false

Send true to return as soon as the message is accepted, with the chatUid to poll, instead of waiting for the assistant to finish.

language
string

Language the assistant has to answer in, as a language code (en, es, fr, ...). Overrides whatever the prompt says for this message only.

skipSummarization
boolean
default:false

Send true to skip the per-message summaries. Saves a secondary model call, so it cuts latency and cost when nothing reads summary.

messageTemplate
string

Turns on payload-template mode. The request body stops being a ProcessMessageRequest and is taken as an opaque payload, and the message text is rendered from this template: {{path.to.field}} resolves a dot-path into the body, {{$date}} resolves to the current server date (YYYY-MM-DD, see tz).

In this mode every other body field — metadata, tenantId, provider, model, ... — is ignored, so an external payload cannot set them. A template that renders an empty string (a sticker, a reaction, an unrelated event) is acknowledged with 200 and no run, so the sender does not retry.

chatUidTemplate
string

Template for the chatUid in payload-template mode, same syntax as messageTemplate and only valid together with it. Use it to derive the conversation grouping from the payload, for example one conversation per source chat per day. When omitted, or when it renders empty, a new chatUid is generated.

userNameTemplate
string

Template for the userName in payload-template mode, same syntax as messageTemplate and only valid together with it.

tz
string

IANA timezone used to resolve {{$date}} in the templates. Defaults to UTC; an invalid value falls back to UTC.

Body

application/json

The message to send and the context it is sent with. In payload-template mode the body is instead the third-party payload the templates read from.

One user message and the context it is sent with. The assistant answers that single message; the rest of the conversation is recovered from chatUid.

message
string
required

The user message the assistant has to answer. Required, except in payload-template mode (messageTemplate query parameter), where the body is an opaque third-party payload and the text is rendered from the template instead.

Example:

"What solar panels do you recommend?"

chatUid
string

Conversation to continue. Omit it to start a new one: the generated id comes back on the messages of the response (and, in async mode, in the acknowledgement), and is what you send on the next call.

Example:

"550e8400-e29b-41d4-a716-446655440000"

userName
string

Name of the end user writing, used for personalisation and shown in the conversation logs.

Example:

"John Doe"

tags
string[]

Tags stored on the conversation, to filter it later from the chat listing endpoints.

Example:
files
object[]

Files attached to the message. Upload them first with the file upload endpoint, then pass the returned download URL here.

images
object[]

Images attached to the message, always as URLs (never base64). Requires a vision-capable model.

metadata
object

Free-form context stored on the conversation. Two keys are read by the platform; anything else is kept as-is and can be read back from the chat history.

Example:
tenantId
string

Tenant (customer/organization) this conversation belongs to in multi-tenant setups. Auto-registers the tenant on first use and attributes its cost/usage. See the Tenants endpoints.

Example:

"tenant_12345"

subtenantId
string

End user/entity inside the tenant. When omitted it is derived from metadata.subtenantMetadata.id or the legacy metadata.userId. Used for per-subtenant cost attribution and usage limits.

Example:

"user_67890"

previousConversation
object[]

Earlier exchanges to seed the conversation with, for example when migrating a chat from another system. Only accepted when starting a new conversation, that is, without chatUid.

Example:
enabledTools
string[]

Restricts this message to these tools, by name, out of the ones the assistant's tool servers offer. Omit the field to leave the assistant's own configuration alone; send an empty array to run the message with no tools at all.

Example:
disabledIntegrations
string[]

Apps the end user connected that should sit out this message, by slug. A deny list over the tenant's own connected apps only — the assistant's tool servers are governed by enabledTools. The account stays connected and the next message has it back unless it is named again.

Example:
provider
enum<string>

Overrides the assistant's LLM provider for this message. The account must have that provider configured.

Available options:
open-ai,
anthropic,
google-gemini,
deepseek,
kimi,
xai
Example:

"open-ai"

model
string

Overrides the assistant's model for this message. Must be a supported model and, when provider is also sent, must belong to it.

Example:

"gpt-4.1"

tools
object[]

Model Interface Protocol: tools that run on your side. When the assistant calls one, the turn stops with the call pending and you answer it with the tool-response endpoint.

transcriptId
string

Id of a speech-to-text transcript (from the transcription endpoint) that seeded this message, so the conversation keeps a link to the original audio.

Example:

"550e8400-e29b-41d4-a716-446655440000"

Response

Synchronously, the messages the turn produced, oldest first, with the assistant reply last. In async mode, the acknowledgement with the chatUid to poll.

A single message of a conversation, as the platform stored it.

uid
string

Unique message id

Example:

"75ecbcfc-a3be-43ba-8da6-b3e16e8d7280"

chatUid
string

Conversation this message belongs to

Example:

"550e8400-e29b-41d4-a716-446655440000"

role
enum<string>

Who the message is from. developer messages are the ones the platform injects (current date, injected context) and can be ignored by most clients.

Available options:
user,
assistant,
developer,
tool
content
object

Body of the message.

timestamp
number

Unix timestamp in milliseconds

Example:

1706000000000

userUID
string

Identity the message was written under

Example:

"api-key:42"

summary
string

Short AI-generated summary of the message, unless summarisation was skipped

Example:

"The user asks which panels to install on a 60 m2 roof."

contentSource
string

Where content.message came from when the model did not write it. finish_tool means the reply was taken from the finish tool's message argument, so it can be read without parsing tool calls. Absent on messages the model wrote itself.

Example:

"finish_tool"

tool_calls
object[]

Tool calls the assistant made on this message

tool_call_id
string

On tool messages, the call this message answers

Example:

"call_abc123"

latencyMs
number

How long the model or the tool took, in milliseconds

Example:

1045

messageTokenUsage
object

Tokens this message accounted for

messageCost
object

What this message cost, at the pricing in force when it ran