---
title: "Create conversation"
method: POST
path: "/beta/conversations"
tags: ["Conversations", "Chatbots"]
---

# Create conversation

`POST /beta/conversations`

Create a conversation. For inbound messages the author is assumed to be the requester of the conversation (end user). For outbound messages the author is specified using the agentId field.

## Request body

- union
  - Callback
    - `requesterId` string, uuid, required — The end user's userId
    - `direction` string, required — values: [Inbound, Outbound]
    - `contactEndpointId` string, required
    - `queueId` string, uuid, required
  - Chat
    - `requesterId` string, uuid, required — The end user's userId
    - `widgetId` string, uuid, required
    - `message` union, required — Only Outbound messages are supported for Sms and Whatsapp.
      - Inbound
        - `content` union, required
          - Html
            - `value` string, required
          - Markdown
            - `value` string, required
          - Text
            - `value` string, required
        - `attachments` File[]
          - `url` string, required — url
          - `prettyName` string
        - `integrationEmail` string — Internal email address registered for the integration with format: \<email-address\>@email.dixa.io
        - `externalId` string — Client generated identifier for external reference
      - Outbound
        - `content` union
          - Html
            - `value` string, required
          - Markdown
            - `value` string, required
          - Text
            - `value` string, required
        - `agentId` string, uuid, required
        - `attachments` File[]
          - `url` string, required — url
          - `prettyName` string
        - `integrationEmail` string
        - `externalId` string
        - `cc` string[]
        - `bcc` string[]
    - `browserInfo` BrowserInfo
      - `name` string, required
      - `version` string
      - `ipAddress` string
      - `originatingUrl` string
    - `language` string
  - ContactForm
    - `requesterId` string, uuid, required — The end user's userId
    - `emailIntegrationId` string, required
    - `subject` string, required
    - `message` union, required — Only Outbound messages are supported for Sms and Whatsapp.
      - Inbound
        - `content` union, required
          - Html
            - `value` string, required
          - Markdown
            - `value` string, required
          - Text
            - `value` string, required
        - `attachments` File[]
          - `url` string, required — url
          - `prettyName` string
        - `integrationEmail` string — Internal email address registered for the integration with format: \<email-address\>@email.dixa.io
        - `externalId` string — Client generated identifier for external reference
      - Outbound
        - `content` union
          - Html
            - `value` string, required
          - Markdown
            - `value` string, required
          - Text
            - `value` string, required
        - `agentId` string, uuid, required
        - `attachments` File[]
          - `url` string, required — url
          - `prettyName` string
        - `integrationEmail` string
        - `externalId` string
        - `cc` string[]
        - `bcc` string[]
    - `language` string
  - Email
    - `requesterId` string, uuid, required — The end user's userId
    - `emailIntegrationId` string, required
    - `subject` string, required
    - `message` union, required — Only Outbound messages are supported for Sms and Whatsapp.
      - Inbound
        - `content` union, required
          - Html
            - `value` string, required
          - Markdown
            - `value` string, required
          - Text
            - `value` string, required
        - `attachments` File[]
          - `url` string, required — url
          - `prettyName` string
        - `integrationEmail` string — Internal email address registered for the integration with format: \<email-address\>@email.dixa.io
        - `externalId` string — Client generated identifier for external reference
      - Outbound
        - `content` union
          - Html
            - `value` string, required
          - Markdown
            - `value` string, required
          - Text
            - `value` string, required
        - `agentId` string, uuid, required
        - `attachments` File[]
          - `url` string, required — url
          - `prettyName` string
        - `integrationEmail` string
        - `externalId` string
        - `cc` string[]
        - `bcc` string[]
    - `language` string
  - Sms
    - `requesterId` string, uuid, required — The end user's userId
    - `contactEndpointId` string, required — SMS enabled provisioned phone number in valid E.164 format
    - `message` union, required — Only Outbound messages are supported for Sms and Whatsapp.
      - Inbound
        - `content` union, required
          - Html
            - `value` string, required
          - Markdown
            - `value` string, required
          - Text
            - `value` string, required
        - `attachments` File[]
          - `url` string, required — url
          - `prettyName` string
        - `integrationEmail` string — Internal email address registered for the integration with format: \<email-address\>@email.dixa.io
        - `externalId` string — Client generated identifier for external reference
      - Outbound
        - `content` union
          - Html
            - `value` string, required
          - Markdown
            - `value` string, required
          - Text
            - `value` string, required
        - `agentId` string, uuid, required
        - `attachments` File[]
          - `url` string, required — url
          - `prettyName` string
        - `integrationEmail` string
        - `externalId` string
        - `cc` string[]
        - `bcc` string[]
  - Whatsapp
    - `requesterId` string, uuid, required — The end user's userId
    - `contactEndpointId` string, required — WhatsApp-enabled integration phone number that sends the message
    - `message` WhatsappOutboundMessage, required
      - `agentId` string, uuid, required
      - `template` TemplateInput, required
        - `templateId` string, uuid, required
        - `templateVariableMap` MapString, required

## Response `201`

The id of the created conversation

- CreateConversationOutput
  - `data` ConversationResponse, required
    - `id` integer, required

## Other responses

- `400` — Invalid value extracted from request context, Invalid value for: body, Invalid input for Message, Failure to download attachment, Duplicate externalId, Unsupported ConversationChannel
- `404` — An entity in this request could not be found
- `500` — Internal failure during request processing

---

[API](https://skmtc.net/dixa/apis/dixa-api.md) · [All operations](https://skmtc.net/dixa/apis/dixa-api/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/dixa/dixa-api/revisions/5eaff14a2c46/schema)