Channels

Open a conversation

The outbound-first path: open a conversation for an identifier ahead of any inbound message, which falls out of making the identifier the unit rather than the message. Resolves the same three-layer action an inbound would; a 409 when that does not land on an agent — there is nothing to open for a message/silence outcome.

post/v1/projects/{project_id}/channels/{channel_id}/conversations

Request

  • Base URL: https://api.naturali.ai
  • URL: https://api.naturali.ai/v1/projects/{project_id}/channels/{channel_id}/conversations
  • Auth: one of:
    • HTTP bearer
    • OAuth 2 (authorization code, authorization URL https://api.naturali.ai/authorize, token URL https://api.naturali.ai/token, scopes: mcp:access)

Request body

identifierstring required

The address identifier, in this channel's kind (whatsapp:dm:<phone>, discord:dm:<user_id>); any other form is 400.

Example request

{
  "identifier": "discord:dm:425678901234567890"
}

Response

Conversation opened (or already existing).

idstring required
project_idstring required
channel_idstring required
address_idstring required

The address the dialogue arrived at — the continuity key.

route_idstring required

The route this conversation's action came from — a real route id, or one of the two sentinels for "the address's own action" / "the channel default" (CHANNELS-ROUTING.md §3.8). A message resolving to a different action opens a new conversation rather than re-pointing this one.

identifierstring nullable required

The prefixed, self-describing channel identifier (whatsapp:dm:…, discord:dm:…, discord:thread:…). Read through from the address above.

actor_idstring nullable required

The runtime actor the address speaks as. Null when the address has not needed one yet.

session_idstring required

The runtime session this conversation maps 1:1 to.

created_atstring date-time required
updated_atstring date-time required

Example response

{
  "id": "conv_V1StGXR8Z5jdHi6B",
  "project_id": "proj_V1StGXR8Z5jdHi6B",
  "channel_id": "chan_V1StGXR8Z5jdHi6B",
  "address_id": "addr_V1StGXR8Z5jdHi6B",
  "route_id": "route_V1StGXR8Z5jdHi6B",
  "identifier": "whatsapp:dm:425678901234567890",
  "actor_id": "actor_V1StGXR8Z5jdHi6B",
  "session_id": "sess_V1StGXR8Z5jdHi6B"
}

Changes

No recorded changes to this operation across all 1 revision of this API.