Skip to content
Home/
/
Create Conversation

Create Conversation

Request

Called when a new conversation has been created via the Fin Messenger. Note we provide the initial message from the conversation as we know many help desks require this to be provided when creating a conversation. The response requires both the conversation object and the message object so that these can be mapped correctly to their Fin equivalents.

Security
BearerAuth
Bodyapplication/json
titlestring or null

Conversation title (may be blank)

Example:"Question about pricing"
userobject(UserBasic)

Basic user information for requests

object_idstring

Unique identifier for the conversation in our system

Example:"123456"
attributesobject(ConversationAttributes)

Attributes associated with the conversation

Example:
{
  "issue_type": "Billing",
  "priority": "High"
}
initial_messageobject(MessageInput)

Message input fields for creation. Either body or attachments (or both) must be provided. A message cannot be empty - it must contain either text content or at least one attachment.

POST
/create_conversation
curl -i -X POST \
  https://helpdesk.example.com/api/fin/create_conversation \
  -H 'Authorization: Bearer <YOUR_TOKEN_HERE>' \
  -H 'Content-Type: application/json' \
  -d '{
    "title": "Question about pricing",
    "user": {
      "id": "user_123456",
      "name": "Jane Doe",
      "email": "jane.doe@example.com",
      "photo_url": "https://example.com/avatars/jane.jpg",
      "user_type": "end_user",
      "attributes": {
        "plan_type": "enterprise",
        "signup_date": "2024-01-15",
        "is_premium": true
      }
    },
    "object_id": "123456",
    "attributes": {
      "issue_type": "Billing",
      "priority": "High"
    },
    "initial_message": {
      "message_type": "comment",
      "body": "string",
      "author": {
        "id": "user_123456",
        "user_type": "end_user",
        "name": "Jane Doe",
        "email": "jane.doe@example.com",
        "photo_url": "https://example.com/avatars/jane.jpg"
      },
      "visibility": "public",
      "object_id": "123456",
      "attachments": [
        {
          "url": "https://example.com/files/pricing-guide.pdf",
          "filetype": "pdf",
          "filename": "Pricing Guide 2025"
        }
      ]
    }
  }'

Responses

Conversation created successfully

Bodyapplication/json
dataobject
errorobject or null(ProblemDetails)

The error returned by the API. This is an RFC 7807 problem details object: https://www.rfc-editor.org/rfc/rfc7807.html.

Response
{
  "data": {
    "conversation": { … },
    "message": { … }
  }
}