Skip to main content
POST
/
v1
/
chat
Create a chat
curl --request POST \
  --url https://api.roark.ai/v1/chat \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "startTimestamp": "<string>",
  "endTimestamp": "<string>",
  "messages": [
    {
      "role": "<string>",
      "text": "<string>",
      "startTimestamp": "<string>",
      "languageCode": "<string>",
      "endTimestamp": "<string>",
      "agent": {
        "roarkId": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
        "customId": "<string>"
      }
    }
  ],
  "toolInvocations": [
    {
      "name": "<string>",
      "parameters": {},
      "result": "<string>",
      "startTimestamp": "<string>",
      "description": "<string>",
      "endTimestamp": "<string>",
      "agent": {
        "roarkId": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
        "customId": "<string>"
      }
    }
  ],
  "properties": {
    "source": "web",
    "region": "US",
    "sessionId": "abc123"
  },
  "traceId": "4bf92f3577b34da6a3ce929d0e0e4736",
  "externalId": "<string>",
  "agent": {
    "roarkId": "3c90c3cc-0d44-4b50-8888-8dd25736052a"
  },
  "agents": [
    {
      "roarkId": "3c90c3cc-0d44-4b50-8888-8dd25736052a"
    }
  ],
  "customers": [
    {
      "phoneNumberE164": "<string>",
      "label": "<string>"
    }
  ]
}
'
{
  "data": {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "projectId": "660e8400-e29b-41d4-a716-446655440001",
    "organizationId": "770e8400-e29b-41d4-a716-446655440002",
    "startTimestamp": "2024-01-15T10:00:00Z",
    "endTimestamp": "2024-01-15T10:30:00Z",
    "durationMs": 1800000,
    "title": "Account assistance request",
    "summary": "Customer inquired about account balance and recent transactions",
    "createdAt": "2024-01-15T10:31:00Z",
    "updatedAt": "2024-01-15T10:31:00Z",
    "simulationJobId": "880e8400-e29b-41d4-a716-446655440003",
    "simulationRunPlanJobId": "990e8400-e29b-41d4-a716-446655440004",
    "agents": [
      {
        "id": "550e8400-e29b-41d4-a716-446655440000"
      }
    ],
    "customers": [
      {
        "phoneNumberE164": null,
        "label": "web-visitor-abc123"
      }
    ],
    "properties": {
      "source": "web",
      "region": "US"
    },
    "policyIds": [
      "550e8400-e29b-41d4-a716-446655440000"
    ],
    "externalId": "session-abc-123"
  }
}

Authorizations

​
Authorization
string
header
required

Bearer authentication header of the form Bearer <token>, where <token> is your auth token.

Body

application/json

Chat creation payload. Supports singular (agent/customer) or plural (agents/customers) formats.

​
startTimestamp
string
required

When the chat started (ISO 8601 format)

​
endTimestamp
string
required

When the chat ended (ISO 8601 format)

​
messages
object[]
required

Ordered list of messages exchanged during the chat

​
toolInvocations
object[]

List of tool invocations made during the chat

​
properties
object

Custom properties to include with the chat. These can be used for filtering and will show in the chat details page

Example:
{
  "source": "web",
  "region": "US",
  "sessionId": "abc123"
}
​
traceId
string | null

Optional OpenTelemetry trace ID for the chat. Surfaces the chat in the tracing tab.

Example:

"4bf92f3577b34da6a3ce929d0e0e4736"

​
externalId
string

A stable identifier from your own system (e.g. session ID, conversation ID) used to correlate this chat with OpenTelemetry traces. Set the same value as a roark.external_id span or resource attribute on your traces and the matching trace will be linked automatically. Must be unique within a project.

Maximum string length: 255
​
agent
object

Single agent participating in the chat. Use this for the simpler API when you have only one agent.

​
agents
object[]

Agents participating in the chat. Each agent requires identification and prompt information.

Agent participating in the chat with their identification and prompt

​
customer
object

Single customer participating in the chat. Use this for the simpler API when you have only one customer.

​
customers
object[]

Customers participating in the chat.

Response

Chat created successfully

​
data
ChatResponse · object
required

Response containing the chat information