> ## Documentation Index > Fetch the complete documentation index at: https://developers.chatwoot.com/llms.txt > Use this file to discover all available pages before exploring further. # Create New Conversation > Creating a conversation in chatwoot requires a source id. Learn more about source_id: https://www.chatwoot.com/hc/user-guide/articles/1677839703-how-to-create-an-api-channel-inbox#send-messages-to-the-api-channel ## Email inboxes When the target inbox is an **Email** inbox, a few extra fields control the subject line and the recipients of the outgoing email. They map to the fields an agent fills in when composing a new email conversation from the dashboard. | Dashboard field | API field | Notes | | - | - | - | | **Via** (From) | `inbox_id` | Not set directly. The From address is resolved from the inbox's configuration. | | **To** | `source_id` + `contact_id` | For an Email inbox, `source_id` is the contact's email address. | | **Subject** | `additional_attributes.mail_subject` | Stored on the conversation and reused for the whole thread. | | **Cc** | `message.cc_emails` | Comma-separated list. | | **Bcc** | `message.bcc_emails` | Comma-separated list. | | — | `message.to_emails` | Comma-separated list. Overrides the contact's email as the recipient. | ```bash theme={null} curl --request POST \ --url https://app.chatwoot.com/api/v1/accounts/{account_id}/conversations \ --header 'api_access_token: ' \ --header 'Content-Type: application/json' \ --data '{ "source_id": "john@example.com", "inbox_id": 1, "contact_id": 1, "additional_attributes": { "mail_subject": "Issue with my recent order" }, "message": { "content": "Hi John, could you share your order number?", "cc_emails": "billing@example.com, support@example.com", "bcc_emails": "archive@example.com" } }' ``` `cc_emails`, `bcc_emails` and `to_emails` belong to the `message` object, not to `additional_attributes`. They are only processed for Email inboxes and are ignored on every other channel. A few things to keep in mind: * All three email lists take a **comma-separated string**, not an array. Whitespace around the addresses is stripped. If any address is not a valid email, the request fails with `Invalid email address`. * `mail_subject` applies to the whole conversation, not just the first message. The first email goes out with the subject as-is; from the second message onwards, replies are sent as `Re: `. Private notes and activity messages are not counted. * If you omit `mail_subject`, Chatwoot falls back to `[#] New messages on this conversation`. * The From address cannot be set per request. It is resolved from the inbox and channel configuration — for inboxes using SMTP or OAuth it is the channel's email address, otherwise it is the inbox's configured email address, falling back to the account's support email. ## OpenAPI ````yaml POST /api/v1/accounts/{account_id}/conversations openapi: 3.1.0 info: title: Chatwoot description: This is the API documentation for Chatwoot server. version: 1.1.0 termsOfService: https://www.chatwoot.com/terms-of-service/ contact: email: hello@chatwoot.com license: name: MIT License url: https://opensource.org/licenses/MIT servers: - url: https://app.chatwoot.com/ security: [] tags: - name: Account AgentBots description: Account-specific Agent Bots - name: Agents description: Agent management APIs - name: Campaigns description: >- Create, schedule, and manage campaigns. Requires an account administrator and API access enabled for the account. - name: Canned Responses description: Pre-defined responses for common queries - name: Contacts description: Contact management APIs - name: Contact Labels description: Manage contact labels - name: Conversation Assignments description: Manage conversation assignments - name: Conversation Labels description: Manage conversation labels - name: Conversations description: Conversation management APIs - name: Custom Attributes description: Custom fields for contacts and conversations - name: Custom Filters description: Saved filters for conversations - name: Inboxes description: Communication channels setup - name: Integrations description: Third-party integrations - name: Labels description: Account label management APIs - name: Messages description: Message management APIs - name: Profile description: User profile APIs - name: Reports description: Analytics and reporting APIs - name: Teams description: Team management APIs - name: Webhooks description: Event notification webhooks - name: Automation Rule description: Workflow automation rules - name: Help Center description: Knowledge base management paths: /api/v1/accounts/{account_id}/conversations: parameters: - $ref: '#/components/parameters/account_id' post: tags: - Conversations summary: Create New Conversation description: |- Creating a conversation in chatwoot requires a source id. Learn more about source_id: https://www.chatwoot.com/hc/user-guide/articles/1677839703-how-to-create-an-api-channel-inbox#send-messages-to-the-api-channel operationId: newConversation requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/conversation_create_payload' responses: '200': description: Success content: application/json: schema: type: object properties: id: type: number description: ID of the conversation account_id: type: number description: Account Id inbox_id: type: number description: ID of the inbox '403': description: Access denied content: application/json: schema: $ref: '#/components/schemas/bad_request_error' security: - userBearerAuth: [] - agentBotBearerAuth: [] - userApiKey: [] - agentBotApiKey: [] components: parameters: account_id: in: path name: account_id schema: type: integer required: true description: The numeric ID of the account schemas: conversation_create_payload: type: object required: - source_id properties: source_id: type: string description: Conversation source id example: '1234567890' inbox_id: type: integer description: >- Id of inbox in which the conversation is created
Allowed Inbox Types: Website, Phone, Api, Email example: 1 contact_id: type: integer description: Contact Id for which conversation is created example: 1 additional_attributes: type: object description: Lets you specify attributes like browser information example: browser: Chrome browser_version: 89.0.4389.82 os: Windows os_version: '10' custom_attributes: type: object description: >- The object to save custom attributes for conversation, accepts custom attributes key and value example: attribute_key: attribute_value priority_conversation_number: 3 status: type: string enum: - open - resolved - pending description: Specify the conversation whether it's pending, open, closed example: open assignee_id: type: integer description: Agent Id for assigning a conversation to an agent example: 1 team_id: type: integer description: Team Id for assigning a conversation to a team\ example: 1 snoozed_until: type: string format: date-time description: Snoozed until date time example: '2030-07-21T17:32:28Z' message: type: object description: The initial message to be sent to the conversation required: - content properties: content: type: string description: The content of the message example: Hello, how can I help you? template_params: type: object description: The template params for the message in case of whatsapp Channel properties: name: type: string description: Name of the template example: sample_issue_resolution category: type: string description: Category of the template example: UTILITY language: type: string description: Language of the template example: en_US processed_params: type: object description: >- The processed param values for template variables in template example: '1': Chatwoot bad_request_error: title: data type: object properties: description: type: string errors: type: array items: $ref: '#/components/schemas/request_error' request_error: type: object properties: field: type: string message: type: string code: type: string securitySchemes: userBearerAuth: type: http scheme: bearer description: >- Authenticate with `Authorization: Bearer ` using a user API token from **Profile Settings**. Available in Chatwoot `v4.19.0` and later. agentBotBearerAuth: type: http scheme: bearer description: >- Authenticate with `Authorization: Bearer ` using an agent bot token from **Settings → Agent Bots**. Available in Chatwoot `v4.19.0` and later. userApiKey: type: apiKey in: header name: api_access_token description: >- Find your API token in **Profile Settings**. The `api_access_token` header remains supported, but will be deprecated in a future release. For new integrations, use Bearer authentication. agentBotApiKey: type: apiKey in: header name: api_access_token description: >- Find your agent bot token in **Settings → Agent Bots**. For new integrations, use Bearer authentication in Chatwoot `v4.19.0` and later. Agent bot tokens can access only bot-permitted APIs. ```` This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.