Skip to main content
POST
https://api.getpoppy.ai
/
api
/
bots
/
{botId}
/
conversations
{
  "prompt": "Cola vs Fanta. Which should I pick?"
}

{
  "data": [
    {
      "id": "6de563f8-9b05-4710-9b46-4dd6761e2942",
      "name": "Cola vs Fanta",
      "user_id": "test-firebase-id-1234",
      "chatbot_id": "9c050854-b29f-44fe-a00d-7b3e5dc42fba",
      "messages": [],
      "created_at": "2025-04-23T09:09:59.619Z"
    }
  ]
}
This endpoint creates a new conversation for a specific bot and authenticated end user.

​
URL Parameters

​
botId
string
required
The ID of the bot that the conversation belongs to

​
Headers

​
chatbot-token
string
required
JWT token for the end user. Generate this via POST /api/bots/auth using your API key and the user’s email, then pass it as the chatbot-token header.

​
Request Body

​
prompt
string
required
Initial text used to name the conversation. The name is set to the text before the first ”.”

​
Response

​
data
array
The newly created conversation record
​
data[].id
string
Unique identifier for the conversation
​
data[].name
string
Conversation name derived from the prompt
​
data[].user_id
string
The end user ID that owns the conversation
​
data[].chatbot_id
string
The bot ID that the conversation is associated with
​
data[].messages
array
Conversation messages (empty on creation)
​
data[].created_at
string
ISO timestamp when the conversation was created
{
  "prompt": "Cola vs Fanta. Which should I pick?"
}

{
  "data": [
    {
      "id": "6de563f8-9b05-4710-9b46-4dd6761e2942",
      "name": "Cola vs Fanta",
      "user_id": "test-firebase-id-1234",
      "chatbot_id": "9c050854-b29f-44fe-a00d-7b3e5dc42fba",
      "messages": [],
      "created_at": "2025-04-23T09:09:59.619Z"
    }
  ]
}

{
  "error": "Unauthorized",
  "details": {}
}

{
  "error": "Not found",
  "details": {
    "botId": "8c050854-b29f-44fe-a00d-7b3e5dc42fba not found"
  }
}
Creating a conversation does not send a message to the bot. To send a message, use POST /api/bots/ /conversations/ after you create the conversation.