# Create Conversation

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.

Endpoint: POST /create_conversation
Version: 0.0.1
Security: BearerAuth

## Request fields (application/json):

  - `title` (string,null)
    Conversation title (may be blank)
    Example: "Question about pricing"

  - `user` (object)
    Basic user information for requests

  - `user.id` (string)
    Unique identifier for the user in your system
    Example: "user_123456"

  - `user.name` (string)
    User's display name
    Example: "Jane Doe"

  - `user.email` (string)
    User's email address
    Example: "jane.doe@example.com"

  - `user.photo_url` (string)
    URL to user's avatar/profile picture (displayed in Fin Messenger)
    Example: "https://example.com/avatars/jane.jpg"

  - `user.user_type` (string)
    Type of user
    Enum: "end_user"

  - `user.attributes` (object,null)
    Attributes associated with the end-user
    Example: {"plan_type":"enterprise","signup_date":"2024-01-15","is_premium":true}

  - `object_id` (string)
    Unique identifier for the conversation in our system
    Example: "123456"

  - `attributes` (object)
    Attributes associated with the conversation
    Example: {"issue_type":"Billing","priority":"High"}

  - `initial_message` (object)
    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.

  - `initial_message.message_type` (string)
    Type of message
    Enum: "comment"

  - `initial_message.body` (string,null)
    Message content in HTML format.

Supported HTML tags are:
- Paragraphs `
- Heading 1, Heading 2   (note h3 to h6 appears as a h2)
- Bold 
- Italic 
- Links 
- Images  (can be linked)
- Line breaks 
- Code blocks 
- Unordered lists 
- Ordered lists `
    Example: "<p>Hi! I'd like to know more about your pricing plans.</p>"

  - `initial_message.author` (object)
    The user who authored the message

  - `initial_message.visibility` (string)
    Who can see the message:
- public - Visible to end-users (appears in Fin Messenger)
- private - Only visible to agents (internal notes)
    Enum: "public", "private"

  - `initial_message.object_id` (string)
    Unique identifier for the message in our system
    Example: "123456"

  - `initial_message.attachments` (array)
    Array of attachments (can be empty)

  - `initial_message.attachments.url` (string)
    URL where the attachment can be accessed.
Must be HTTPS. Consider using signed URLs with expiration for sensitive files.
    Example: "https://example.com/files/pricing-guide.pdf"

  - `initial_message.attachments.filetype` (string)
    File type/extension.
    Example: "pdf"

  - `initial_message.attachments.filename` (string)
    Display name for the file
    Example: "Pricing Guide 2025"

## Response 200 fields (application/json):

  - `data` (object)

  - `data.conversation` (object, required)

  - `data.conversation.id` (string, required)
    Unique identifier for the conversation in your system
    Example: "conv_456"

  - `data.conversation.status` (string, required)
    Current conversation status:
- open - Conversation is actively ongoing with the end-user
- resolved - Conversation is resolved by Fin
- closed - Conversation is finished/archived
- ended - Conversation is ended by the end-user or agent
    Enum: "open", "resolved", "closed", "ended"

  - `data.conversation.user` (object, required)
    End user having a conversation with Fin or with an agent.

  - `data.conversation.user.id` (string, required)
    Unique identifier for the user in your system
    Example: "user_123456"

  - `data.conversation.user.user_type` (string, required)
    Type of user
    Enum: "end_user"

  - `data.conversation.user.name` (string,null)
    User's display name
    Example: "Jane Doe"

  - `data.conversation.user.email` (string,null)
    User's email address
    Example: "jane.doe@example.com"

  - `data.conversation.user.photo_url` (string,null)
    URL to user's avatar/profile picture (displayed in Fin Messenger)
    Example: "https://example.com/avatars/jane.jpg"

  - `data.conversation.user.attributes` (object,null)
    Attributes associated with the end-user
    Example: {"plan_type":"enterprise","signup_date":"2024-01-15","is_premium":true}

  - `data.conversation.title` (string,null)
    Conversation title or subject
    Example: "Question about pricing plans"

  - `data.conversation.tags` (array,null)
    List of tags associated with the conversation in your system. Can be used to power routing within the Fin workflow among other things.
    Example: ["pricing","sales"]

  - `data.conversation.attributes` (object)
    Attributes associated with the conversation
    Example: {"issue_type":"Billing","priority":"High"}

  - `data.conversation.assignee` (object,null)
    Agent having a conversation with an end-user.

  - `data.conversation.assignee.alias_name` (string,null)
    Agent's display alias_name (shown to end-users instead of real name)
    Example: "Support Jane"

  - `data.conversation.created_at` (string, required)
    When the conversation was created (ISO 8601 UTC)
    Example: "2025-10-27T14:30:00.000Z"

  - `data.conversation.updated_at` (string, required)
    When the conversation was last updated (ISO 8601 UTC)
    Example: "2025-10-27T15:45:00.000Z"

  - `data.message` (object, required)
    A message in a conversation. 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.

  - `data.message.id` (string, required)
    Unique identifier for the message in your system
    Example: "msg_001"

  - `data.message.conversation_id` (string, required)
    ID of the parent conversation
    Example: "conv_456"

  - `data.message.message_type` (string, required)
    Type of message
    Enum: "comment"

  - `data.message.body` (string,null)
    Message content in HTML format.

Supported HTML tags are:
- Paragraphs `
- Heading 1, Heading 2   (note h3 to h6 appears as a h2)
- Bold 
- Italic 
- Links 
- Images  (can be linked)
- Line breaks 
- Code blocks 
- Unordered lists 
- Ordered lists `
    Example: "<p>Hi! I'd like to know more about your pricing plans.</p>"

  - `data.message.author` (any, required)
    The user who authored the message.

  - `data.message.visibility` (string, required)
    Who can see the message:
- public - Visible to end-users (appears in Fin Messenger)
- private - Only visible to agents (internal notes)
    Enum: "public", "private"

  - `data.message.created_at` (string, required)
    When the message was created (ISO 8601 UTC)
    Example: "2025-10-27T14:35:00.000Z"

  - `data.message.attachments` (array)
    Files attached to the message

  - `data.message.attachments.url` (string)
    URL where the attachment can be accessed.
Must be HTTPS. Consider using signed URLs with expiration for sensitive files.
    Example: "https://example.com/files/pricing-guide.pdf"

  - `data.message.attachments.filetype` (string)
    File type/extension.
    Example: "pdf"

  - `data.message.attachments.filename` (string)
    Display name for the file
    Example: "Pricing Guide 2025"

  - `error` (object)
    The error returned by the API. This is an RFC 7807 problem details object: .

  - `error.type` (string)
    A URI reference that identifies the problem type.

  - `error.title` (string)
    A short, human-readable summary of the problem type.

  - `error.status` (integer)
    The HTTP status code generated by the origin server for this occurrence of the problem.

  - `error.detail` (string)
    A human-readable explanation specific to this occurrence of the problem.

  - `error.instance` (string)
    A URI reference that identifies the specific occurrence of the problem.