> ## Documentation Index
> Fetch the complete documentation index at: https://developers.partoo.co/llms.txt
> Use this file to discover all available pages before exploring further.

# Custom Channels

> Connect your own messaging sources like chatbots, CRMs, or internal tools directly to Partoo

<Warning>
  This feature is available only for businesses subscribed to the Messages Product.
</Warning>

A custom channel allows you to connect your own messaging source directly to Partoo. This enables you to centralize all your customer communications in one place while maintaining your existing messaging infrastructure.

## Prerequisites

Before setting up a custom channel, ensure you have:

* Active subscription to the Messages Product
* [API key with ORG\_ADMIN or PROVIDER rights](/guides/api/resources/settings/security_and_api_key_usage)

<Tip>
  If you need help with any of these prerequisite, please contact your Account Manager who can guide you through the process.
</Tip>

<AccordionGroup>
  <Accordion title="1 - Setting up the Channel">
    ## Channel configuration

    To integrate a custom channel, you need to contact our Account Manager to activate the channel. We'll help you set up the integration with the following information:

    <Steps>
      <Step title="Gather required information">
        Send to your support contact the following details for your custom channel:

        * **name**: Display name for your custom channel
        * **icon**: (Optional) URL to an image for the channel's icon
        * **is\_readonly**: Channel communication mode (see next step)
      </Step>

      <Step title="Choose communication mode">
        Decide whether your channel should be read-only or bidirectional:

        <Tabs>
          <Tab title="Read-only (is_readonly: true)">
            * Messages can only be sent **TO Partoo**
            * Simpler setup with no webhook requirements
            * Ideal for notification systems or logging
          </Tab>

          <Tab title="Bidirectional (is_readonly: false)">
            * Messages can be sent both ways
            * Replies from Partoo app or API are possible

            <Warning>
              You must subscribe to the [Message Created](/api-reference/webhooks-events/message-created) webhook to receive and process replies from Partoo, as they are not automatically sent back to your system. To know more about webhooks, please refer to the [Webhooks guide](/guides/api/resources/settings/webhooks)
            </Warning>
          </Tab>
        </Tabs>
      </Step>

      <Step title="Contact support and receive channel_id">
        Reach out to our support team with your configuration requirements.

        <Check>
          After configuration, you'll receive a `channel_id` that you'll need for implementing the message flow.
        </Check>
      </Step>
    </Steps>
  </Accordion>

  <Accordion title="2 - Implementing the Custom Channel">
    <Tip>
      Before you start this phase, make sure that you have received the `channel_id` from the setup phase.
      Also make sure that you have access to the webhook endpoints (for bidirectional channels only).
    </Tip>

    ## Send messages from your custom channel to Partoo

    Once your custom channel is configured, you can use the message ingestion endpoint to send messages to Partoo from your custom channel.

    ```
    POST /custom-channels/{channel_id}/messages
    ```

    <Tip>
      You can find more about the endpoint in the [API Reference](/api-reference/custom-channels/ingest-message).
    </Tip>

    ### How the endpoint works

    This endpoint creates new messages in conversations that use custom channels.

    Key behaviors to consider:

    * If the conversation exists, the message is added to it
    * If the conversation doesn't exist, it's automatically created before adding the message
    * Messages are processed asynchronously for better performance
    * `external_conversation_id`& `external_message_id` enable you to correlate webhook messages with the corresponding conversations in your internal system.
    * Messages with the same `external_message_id` & `channel_id` are considered duplicates and ignored
    * Messages with the same `external_conversation_id` & `channel_id` are grouped in the same Partoo conversation

    <Warning>
      A 200 OK response indicates the request was received and accepted for processing, but doesn't guarantee the message was successfully created. Monitor your webhook events or check the conversation to verify message delivery.
    </Warning>

    ## Receive messages from Partoo to your custom channel (for bidirectional channels)

    If you configured your channel as bidirectional (`is_readonly: false`), you need to handle incoming replies from Partoo

    <Steps>
      <Step title="Subscribe to webhooks">
        Set up webhook subscription for [Message Created](/api-reference/webhooks-events/message-created) events to receive replies sent from Partoo.

        <Tip>
          You can find more about webhooks in the [Webhooks guide](/guides/api/resources/settings/webhooks).
        </Tip>
      </Step>

      <Step title="Process incoming messages">
        When Partoo users reply to messages, you'll receive webhook notifications that you need to process and route back to your system.
      </Step>
    </Steps>

    <Check>
      You've successfully configured your custom messaging channel! Your integration is now ready to handle messages through Partoo's messaging platform.
    </Check>
  </Accordion>
</AccordionGroup>