Skip to main content
Create conversation
curl --request POST \
  --url https://api.dimedove.com/v1/apps/{app_id}/conversations \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "external_user_id": "user_abc123",
  "title": "Support inquiry",
  "metadata": {
    "first_name": "John",
    "plan_type": "term_life"
  }
}
'
{
  "id": "<string>",
  "created_at": 123,
  "object": "conversation",
  "external_user_id": "<string>",
  "title": "<string>",
  "generated_title": {
    "en-ca": "<generated title in English>",
    "fr-ca": "<generated title in French>"
  },
  "metadata": {
    "first_name": "John",
    "last_name": "Doe",
    "city": "Montreal"
  }
}

Authorizations

​
Authorization
string
header
required

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

Path Parameters

​
app_id
string
required

The unique identifier of the app.

Body

application/json
​
external_user_id
string | null

Your application's unique identifier for the user. When provided, conversations are linked to this user for retrieval via the list user conversations endpoint.

​
title
string | null

A custom title for the conversation. If not provided, the system will auto-generate a title after the first exchange.

​
metadata
Metadata · object

Arbitrary key-value context to enrich the AI agent's responses for this conversation. Injected into the agent's runtime context on every response. Can be updated by passing metadata on subsequent message requests. Maximum 16KB.

Response

OK

​
id
string
required

Unique identifier for the conversation.

​
created_at
integer
required

Unix timestamp (in seconds) of when the conversation was created.

​
object
string
default:conversation

The object type. Always 'conversation'.

​
external_user_id
string | null

The external user identifier associated with this conversation, if one was provided at creation.

​
title
string | null

The custom title set for this conversation, if any.

​
generated_title
Generated Title · object

AI-generated conversation title in supported locales. Keys are locale codes (e.g. 'en-ca', 'fr-ca').

Example:
{
  "en-ca": "<generated title in English>",
  "fr-ca": "<generated title in French>"
}
​
metadata
Metadata · object

The latest metadata snapshot associated with this conversation, if any has been provided.

Example:
{
  "first_name": "John",
  "last_name": "Doe",
  "city": "Montreal"
}