Deploy your bot to different platforms¶

To link a channel to your bot:

1. Navigate to the Chatbot you wish to embed.
2. Click on the (plus) icon and select the provider from the dropdown.
3. Complete the form and click Create. Follow the guide below to get the required information for each channel.

You may need to Configure a messaging provider before you will be able to select it from the dropdown.

Web and API¶

The web channel uses the web interface and is enabled by default for all bots. Likewise, all bots can be accessed via the APIs.

Telegram¶

• Follow this guide to create a Telegram bot.
• Copy the bot token and paste it into the form on OCS. It will look something like this: 4839574812:AAFD39kkdpWt3ywyRZergyOLMaJhac60qc.

WhatsApp¶

Open Chat Studio supports multiple WhatsApp providers. Choose the section below that matches the provider you have configured.

Twilio and Turn.io¶

Setting Up Your WhatsApp Channel¶

1. Add your WhatsApp number to the form in the Open Chat Studio channels section.

2. Configure the webhook URL in your provider:

The webhook URL is always: https://openchatstudio.com/channels/whatsapp/incoming_message

This URL is the same for all WhatsApp chatbots and channels on Open Chat Studio.

Provider-Specific Configuration¶

For New WhatsApp Numbers¶

If you're setting up a brand new WhatsApp number, you'll need: - Admin access to your Twilio/Turn.io account - To register the number with Meta/WhatsApp - To configure the webhook URL in your provider settings

For Existing WhatsApp Numbers¶

If you're reusing an existing WhatsApp number that was previously configured for Open Chat Studio: - No additional webhook configuration needed - the number is already set up to forward messages to Open Chat Studio - Simply add the number to your bot's channels in Open Chat Studio

Provider Instructions¶

• For Twilio: See this page to configure the webhook URL in your messaging service
• For Turn.io: Go to Settings → API & Webhooks → Add a webhook and paste the OCS webhook URL

Meta Cloud API¶

Meta Cloud API connects your chatbot directly to the WhatsApp Business Platform without a third-party intermediary. The setup requires a Meta for Developers account and a WhatsApp Business Account.

See the Meta Cloud API setup guide for full step-by-step instructions.

Facebook Messenger¶

• Add the ID of your Facebook page.
• After you submit the form, you will be provided with a webhook URL. Copy this URL and navigate back to your provider's settings to configure it with this URL.
  • For Twilio, edit your Facebook page settings and paste the URL into the "Webhook URL for incoming messages" field.

Slack¶

Prerequisites¶

Before configuring a Slack channel for your bot, you need to set up a Slack messaging provider. This requires:

• Admin access to your Slack workspace
• Following the Slack OAuth and application installation flow
• Configuring the messaging provider in Open Chat Studio (see Configure a messaging provider)

Once your Slack messaging provider is configured, you can link channels to your bot.

Configuration Options¶

There are three different ways to configure how your bot responds to messages in Slack. The bot will check each configuration in order of priority:

1. Respond to messages from a single channel (Highest Priority)¶

• Specify the channel name (with or without the '#' prefix) in the channel configuration form.
• This is the highest specificity - messages on this channel will only be responded to by this bot.
• Only one bot can be configured per Slack channel.

2. Respond to messages from any channel using keyword matching¶

• Enter keywords separated by commas in the keyword field (e.g., support, help, assistance).
• Keywords are matched using exact word matching (case-insensitive) to the first word of the user's message.
• Multiple keywords can be used to trigger the bot.
• Keywords must be unique to this bot & Slack workspace combination.

3. Respond to messages from all channels (Lowest Priority)¶

• The bot will respond to any message on any channel if it hasn't matched one of the previous two configurations.
• This is the lowest priority matching option.
• Only one bot per Slack workspace can be configured with this option.

Bot Interaction¶

Once the channel is linked, users interact with the bot by mentioning it in Slack messages. The bot mention name is determined by your Slack app configuration. For example, on the Dimagi hosted instance of Open Chat Studio, the bot is mentioned using @Dimagi Bots.

SureAdhere¶

• Enter the Tenant ID that would have been provided to you when setting up your SureAdhere account.
• After you submit the form, you will be provided with a webhook URL. Copy this URL and navigate back to your provider's settings to configure it with this URL.

Email¶

The email channel lets users interact with your bot by sending and receiving emails.

Configuration¶

When creating an email channel, the form has the following fields:

• Email address: The inbound address that users send messages to. Incoming emails addressed to this value are routed to this bot.
• From address: The address that appears in the "From" field of outgoing replies.
• Default channel: When enabled, this channel acts as the fallback for inbound emails that do not match any other configured email address in your workspace.

How routing works¶

Inbound emails are matched to the correct bot in this order:

1. In-Reply-To header - If the email is a reply to a previous message sent by the bot, it is routed to the same channel and continues the existing conversation thread.
2. To address - If no prior thread is found, the recipient address is matched against configured email channels.
3. Default channel - If no address match is found, the email is delivered to the workspace's default email channel (if one is configured).

Thread continuity¶

Replying to a bot email continues the same conversation session. Sending a fresh email to the channel address starts a new session.

Customizing the outbound subject¶

When the bot starts a new email thread (for example, via the Trigger Bot Message API), the subject line defaults to "New message". To override this, set an email_subject value in session state before the email is sent — for example from a pipeline's Python node, or via the session_data parameter when triggering the bot. Inbound reply threads always reuse the subject of the original email and are unaffected by this value.

File attachments¶

The email channel supports bidirectional file attachments.

Inbound attachments (user to bot)¶

When a user emails files to the bot, each attachment is saved and made available to the LLM or pipeline as a file record. Attachments behave like files uploaded through any other channel: they appear in the attachments list in the pipeline's temporary state and are passed to the LLM for processing.

The following attachments are rejected automatically:

Rejection notes are inserted inline into the user's message so the bot can read them and explain the problem to the user in its reply.

Outbound attachments (bot to user)¶

Files produced by the pipeline are sent as MIME attachments in the same threaded reply as the bot's text response. To attach a file from a Python node, call add_file_attachment():

def main(input, **kwargs) -> str:
    response = http.get("https://api.example.com/report.pdf", auth="reports-api")

    if response["is_success"]:
        add_file_attachment(
            filename="report.pdf",
            content=response["response_bytes"]
        )
        return "I've attached the report."

    return "Failed to retrieve the report."

See the Python Node documentation for the full add_file_attachment() API reference.

If a pipeline-produced file cannot be sent as an attachment (for example, it exceeds the size limit or is a denylisted type), the email body will contain an inline download link for that file instead.