Skip to main content

Create a new Conversation

POST 
/v1/conversations

A Conversation is a collection of Messages that represent a discussion between a user and an agent.

When creating a Conversation, you specify:

  • A friendly name for the Conversation - these names are not unique and are for convenience only.
  • A key identifying the API Key that the agent can use to access the resources it may need to provide a response. If unspecified, the agent will use the API Key used to post a message to the Conversation.

Once a Conversation has been created, you can interact by posting Messages to it via /conversations/:conversationId/messages. These Messages can represent user's responses but they can also be used to force the agent to answer or the change the Context of the conversation.

The Conversation will not start right away. If you want the agent to post first, create a Message with role: 'control' and action: 'generate-reply'. You can use this as an opportunity to set the starting Playbook, SystemMessage or Context for the conversation.

Concepts​

  • Playbook: At any time, a conversation uses a Playbook that determines how the agent behaves. This must be one of Numeno's predefined Playbooks. Use neutral for a general agent. Many Playbook have different Phases that correspond to what the agent is currently trying to do (eg. greet, search/refine-topic, etc.).

  • SystemMessage: A message passed to the agent to help them understand their objective. It is invisible to the user. A Playbook determines a agent's SystemMessage dynamically but you can override it by providing your own.

  • Context: A list of Numeno resources that the agent can examine to provide its response. You can also include custom objects in plain text (we recommend representing them as JSON).

Limits​

The maximum number of Conversations you can create depends on your subscription plan.

Request​

Responses​

Conversation created successfully