😇

Channels

9 articles Ruut CSM Mona By Ruut CSM and Mona

This is the help center articles that highlights everything around channels and how to set it up

How to setup an API inbox on Ruut

How to create an API channel inbox in Ruut Chat The API channel in Ruut Chat is designed for various integration use cases. If you want to build your own custom chat interface that connects directly to Ruut, the API channel is the perfect solution for that. Similarly, if you want to connect our Mobile SDK to Ruut, the API channel is also the best use case for that integration. For SDK users: If you are using the SDK, you just need to create the API channel - no need to add other configurations. After creating the channel, go to your inbox/workspace settings, then under Configuration you would see the workspace inbox identifier that you'll need for your SDK integration. Setup the API channel Step 1. Go to Settings → Workspace → "Add Workspace". Step 2. Click on the "API" icon. - Channel Name: API Support Channel - Callback URL: https://your-app.com/webhooks/ruut-callback Step 4. "Add agents" to your API inbox. The inbox setup is complete. For Mobile Integrations go to the settings of your newly created workspace and check for the configuration and copy the inbox identifier. Send messages to the API channel To send messages to the API channel, ensure you understand the following models and nomenclature used in Ruut Chat. Channel: Channel defines the type of source of conversations. E.g., Facebook, Twitter, API, etc. Inbox: You can create multiple sources of conversations of the same channel type. E.g., You can have more than one Facebook page connected to a Ruut Chat account. Each page is called the inbox in Ruut Chat. Conversation: A Conversation is a collection of messages. Contact: Each conversation has a real-life person associated with it, called a contact. Contact Inboxes: This is the session for each contact in an inbox. A contact can have multiple sessions and multiple conversations in the same inbox. How to send a message in an API Channel? To send a message in an API channel, create a contact, initiate a conversation, and finally send the message. APIs require api_access_token in the request header. You can get this token by visiting your Profile settings → Access Token. 1. Create a contact Ref: API documentation Pass the inbox ID of the API channel along with other params specified. This would create a session for you automatically. A sample response would look like the one below. { "email": "string", "name": "string", "phone_number": "string", "thumbnail": "string", "additional_attributes": {}, "contact_inboxes": [ { "source_id": "string", "inbox": { "id": 0, "name": "string", "website_url": "string", "channel_type": "string", "avatar_url": "string", "widget_color": "string", "website_token": "string", "enable_auto_assignment": true, "web_widget_script": "string", "welcome_title": "string", "welcome_tagline": "string", "greeting_enabled": true, "greeting_message": "string" } } ], "id": 0, "availability_status": "string" } As you can see in the payload, you will be able to see the contact_inboxes and each contact_inbox will have a source_id. Source ID can be seen as the session identifier. You will use this source_id to create a new conversation as defined below. 2. Create a conversation Use the source_id received in the previous API call. You will receive a conversation ID which can be used to create a message. { "id": 0 } 3. Create a new message Ref: API documentation There are 2 types of messages. Incoming: Messages sent by the end user is classified as an incoming message. Outgoing: Messages sent by the agent is classified as an outgoing message. If you call the API with the correct content, you will receive a payload similar to this one: { "id": 0, "content": "This is a incoming message from API Channel", "inbox_id": 0, "conversation_id": 0, "message_type": 0, "content_type": null, "content_attributes": {}, "created_at": 0, "private": false, "sender": { "id": 0, "name": "Pranav", "type": "contact" } } If everything is successful, you will see the conversation on the dashboard as follows. You will be notified when a new message is created on the URL specified while creating the API channel. You can read about the message payload here. Receive messages using callback URL When a new message is created in the API channel, you will get a POST request to the Callback URL specified while creating the API channel. The payload would look like this. Find the full list of events supported by the webhook here. Event type: message_created { "id": 0, "content": "This is a incoming message from API Channel", "created_at": "2025-06-24T15:43:04.000Z", "message_type": "incoming", "content_type": null, "content_attributes": {}, "source_id": null, "sender": { "id": 0, "name": "contact-name", "avatar": "", "type": "contact" }, "inbox": { "id": 0, "name": "API Channel" }, "conversation": { "additional_attributes": null, "channel": "Channel::Api", "id": 0, "inbox_id": 0, "status": "open", "agent_last_seen_at": 0, "contact_last_seen_at": 0, "timestamp": 0 }, "account": { "id": 1, "name": "API testing" }, "event": "message_created" } Create Interfaces using client APIs Client APIs available for the API channel will help you build customer-facing interfaces for Ruut Chat. These APIs are useful for cases like the ones listed below. - Use a custom chat interface instead of the Ruut Chat widget. - Build conversational interfaces into your mobile apps. - Add Ruut Chat to other platforms for which Ruut Chat doesn't have an official SDK. Creating customer objects You can create and retrieve customer data objects using the inbox_identifier and customer_identifier. Inbox Identifier You can obtain the inbox_identifier from your API channel → Settings → Configuration. Customer Identifier The customer_identifier or the source_id can be obtained when creating the customer using the create API. You will need to store this identifier on your client-side to make further requests on behalf of the customer. This can be done in cookies, local storage etc. Available APIs The Available Client APIs are documented here. Some of the things you can do with the APIs are: - Create, View and Update Contact - Create and List Conversations - Create, List and Update Messages HMAC Authentication The Client APIs also support HMAC Authentication. The HMAC token for the Channel can be obtained via running the following on your rails console. # replace api_inbox_id with your inbox id Inbox.find(api_inbox_id).channel.hmac_token Connecting to the Ruut Chat WebSockets To get real-time updates from the agent dashboard, connect to Ruut Chat WebSockets using the following URL. <your installation url>/cable Authenticating your WebSocket connection After subscribing using the customer's pubsub_token, you will receive events directed toward your customer object. The pubsub_token is provided during the customer creation API call. Example const connection = new WebSocket('ws://localhost:3000/cable'); connection.send(JSON.stringify({ command: "subscribe", identifier: "{\"channel\":\"RoomChannel\",\"pubsub_token\":\"" + customer_pubsub_token + "\"}" })); Find the full list of events supported by WebSockets here.

How to Set Up a Telegram Channel on Ruut

If you're a business or support agent using Ruut, integrating your Telegram channel can help you engage with customers more efficiently through a single unified dashboard. This guide walks you through the step-by-step process of setting up a Telegram channel on the Ruut platform. What You Need Before You Start - A Telegram Account - A Telegram Bot (created via BotFather) - Ruut Admin Access - Channel Admin Permissions (if linking a Telegram Channel) Step-by-Step Guide - Step 1: Create a Telegram Bot - Open Telegram and search for @BotFather. - Start a chat and use the /newbot command. - Follow the prompts to: - Name your bot. - Set a unique username ending with bot (e.g., RuutSupportBot). - BotFather will give you a token. Copy this token; you'll need it in Ruut. Step 2: Add the Bot to Your Telegram Channel (If using a Channel) - Go to your Telegram channel. - Tap Channel Info → Administrators → Add Admin. - Search for your bot (e.g., @RuutSupportBot) and add it as an admin. - Grant at least these permissions: - Post messages - Edit messages - Delete messages (optional) Step 3: Log in to Your Ruut Dashboard - Visit https://app.ruut.chat/app/login and log in with your admin account. - Go to Settings > Channels. Step 4: Add Telegram as a Channel - Click “Add Channel” and select Telegram. - Paste the Bot Token you got from BotFather. - (If you're connecting a Telegram group or channel) Enter the channel/group username. - Click "Connect". - Ruut will validate the token and link the bot to your workspace. - Test Your Bot - Send a message from a personal Telegram account to your bot. It should appear in your Ruut inbox. You can now reply to customers from Telegram directly within Ruut! Tips for Smooth Operation - Make sure your bot remains an admin in the channel. - If connecting a group, users must interact with the bot once before Ruut can see their messages. - Use auto-routing and tags in Ruut to manage incoming Telegram messages efficiently.

Set up a WhatsApp Business Account on Meta

To use an official WhatsApp Business number with platforms such as Ruut, your business first needs to set up its business assets with Meta. This guide walks you through creating a Meta Business Portfolio, setting up your WhatsApp Business Account (WABA), adding and verifying your business phone number, completing your business profile, and preparing your account for verification. A WhatsApp Business Account, often shortened to WABA, is the Meta business asset used to manage phone numbers on the official WhatsApp Business Platform. Note: A WhatsApp Business Account on Meta is different from the WhatsApp Business mobile app. The mobile app is designed primarily for managing conversations from a phone, while a WABA is used by the WhatsApp Business Platform and official API integrations. WhatsApp's official onboarding guidance recommends setting up your account, completing business verification, understanding its policies and building a record of high-quality messaging as part of onboarding to the WhatsApp Business Platform. Before you start You should have: - A Facebook account that you control - Your business or brand name - Your company's legal name - A business email address - Your business address - A live business website - Your company registration information, where applicable - A phone number you want to use for WhatsApp - Access to receive an SMS or voice call on that phone number - Authority to manage Meta assets for your organisation We recommend using a Facebook account belonging to a founder, owner, director or long-term administrator rather than an external contractor. 1. Create or open your Meta Business Portfolio Go to Meta Business Suite and sign in with your Facebook account. Open Meta Business Suite A Business Portfolio is the Meta account used to organise your company's business assets. It can contain assets such as: - WhatsApp Business Accounts - Facebook Pages - Instagram accounts - Advertising accounts - Meta apps - Other business assets You may also see older documentation refer to a Business Portfolio as Meta Business Manager. Already have a Business Portfolio? If your organisation already has a Business Portfolio used to manage its Facebook Page, Instagram account or advertising, you should normally use that existing portfolio. Avoid creating duplicate Business Portfolios for the same company unless you have a specific reason to do so. Creating a new Business Portfolio If your company doesn't already have one: 1. Sign in to Meta Business Suite. 2. Open the Business Portfolio selector. 3. Choose Create a business portfolio. 4. Enter your business name. 5. Enter your name. 6. Enter your business email address. 7. Submit the form. 8. Confirm your email address if Meta asks you to. Use the real name of your organisation rather than a generic name such as "WhatsApp Business." 2. Complete your business information Once your Business Portfolio has been created, open: Meta Business Suite → Settings → Business info You can also access Meta's Business Settings directly: Open Meta Business Settings Complete your business information as accurately as possible. This may include: - Legal business name - Business address - Country - Business phone number - Website - Business email address Where Meta asks for your legal business name, enter the name shown on your official registration documents. For example, your customers may know your company as: Acme while your registered company name is: Acme Technologies Limited In that case, use Acme Technologies Limited where Meta specifically requests your legal business name. Your customer-facing brand can still be used as your WhatsApp display name where it clearly represents your business. 3. Make sure your website is ready Meta may use your website and other publicly available information when reviewing your business. Before continuing, make sure your website: - Is publicly accessible - Uses HTTPS - Clearly displays your business or brand name - Explains what your company does - Contains valid contact information - Is consistent with the company being registered If your brand name and legal company name are different, make the relationship reasonably clear. For example: Acme is operated by Acme Technologies Limited. Avoid submitting a placeholder, unfinished or unrelated website. 4. Set up your WhatsApp Business Account The next step is creating or selecting the WhatsApp Business Account (WABA) belonging to your business. Depending on the Meta interface available to your account, you may create or manage the WABA through WhatsApp Manager, Business Settings, or during WhatsApp Business Platform onboarding. In Business Settings, look for: Accounts → WhatsApp Accounts If Meta allows you to add or create an account directly: 1. Select WhatsApp Accounts. 2. Click Add. 3. Choose the option to create a WhatsApp Business Account. 4. Enter the requested business information. 5. Complete the setup. If you already have a WABA belonging to your company, use the existing account rather than creating a duplicate. WhatsApp's official onboarding material identifies setting up the business account, business profile and phone number as part of onboarding to the WhatsApp Business Platform. 5. Open WhatsApp Manager WhatsApp Manager is Meta's management interface for the WhatsApp Business Platform. It is where you can manage items such as: - WhatsApp Business Accounts - Phone numbers - Business profiles - Display names - Message templates - Account quality - Messaging limits - Two-step verification From Meta Business Suite or Business Settings, select your WhatsApp Business Account and open WhatsApp Manager. 6. Add your business phone number Inside WhatsApp Manager, find the Phone numbers section and select the option to add a phone number. Meta will ask for information about your business and the number you want to register. Enter the phone number using its full international format. For example, a Nigerian number should use: +234... rather than beginning with the local 0. Your number needs to be accessible because Meta may verify ownership using an SMS or automated voice call. 7. Choose your WhatsApp display name Your display name is the business name associated with your WhatsApp number. Examples: Ruut Acme Acme Technologies Use a name that customers genuinely associate with your business. Your display name should have a clear relationship with your: - Website - Brand - Company - Products or services - Public business identity Avoid unnecessary promotional text or misleading names such as: ACME OFFICIAL SUPPORT BEST PRICES ✅ or generic names such as: Customer Support WhatsApp's onboarding guidance states that your display name should be consistent with your external branding, such as your website and marketing material. 8. Complete your WhatsApp Business profile Meta may ask you to provide additional information about the business. Complete as much of the profile as possible. This can include: Business category Choose the category that best represents what your organisation does. Examples include: - Software - Retail - Education - Financial services - Professional services - Travel - Healthcare Business description Write a short and accurate description of what your company provides. For example: Acme provides inventory and payment software for retailers across Africa. Website Enter your official website. Contact information Where available, provide a business email address or customer-support contact. WhatsApp's Business Messaging Policy requires businesses to maintain accurate information and prohibits impersonating another business or misleading customers about the nature of the organisation. Read the WhatsApp Business Messaging Policy 9. Verify your phone number Meta needs to confirm that you control the phone number being registered. Depending on the number, Meta may offer: - SMS verification - Voice-call verification Select the method you can access. Meta will send or read a verification code. Enter that code into the verification screen to confirm ownership of the number. Using a landline If Meta offers voice-call verification, a landline can potentially receive the automated verification call. Using an IVR If the number normally answers with something like: Press 1 for Sales. Press 2 for Support. the automated verification call may not reach you successfully. Temporarily route incoming calls directly to someone who can hear the verification code. 10. If the number already uses WhatsApp Be careful if the number is already registered with: - WhatsApp Messenger - WhatsApp Business App - Another WhatsApp Business Platform provider Do not delete an existing WhatsApp account simply because you want to use the WhatsApp Business Platform. Meta has different onboarding and migration paths depending on how the number is currently being used. For eligible WhatsApp Business App accounts, Meta also supports onboarding methods that allow the Business App and Business Platform to coexist. If your number is already connected to another Business Platform provider, use the appropriate migration process rather than creating a completely unrelated WhatsApp account. 11. Set up two-step verification Meta may require a six-digit PIN to protect registration of your WhatsApp business phone number. If you are given the option, enable Two-step verification for the number. Store this PIN somewhere secure. Avoid using: - 123456 - Your phone number - Your company formation year - A PIN shared in public team channels The PIN can become important when managing or migrating your WhatsApp number later. 12. Complete Meta Business Verification Phone-number verification and Business Verification are not the same thing. Phone verification confirms: You control this phone number. Business Verification confirms: The Business Portfolio represents a real business or organisation. WhatsApp includes business verification as part of its official onboarding journey for businesses preparing to scale on the WhatsApp Business Platform. To check whether verification is available for your business, open: Meta Business Suite → Settings → Security Center Look for Business Verification or Start verification. You may be asked for: - Country of registration - Legal company name - Registered address - Business phone number - Website - Business email - Company registration information Follow the instructions shown by Meta. 13. Prepare your business documents Meta may be able to verify some businesses automatically. If it cannot, you may be asked to provide official documents. Depending on your country and business type, these may include documents that demonstrate your: - Legal company name - Registered address - Registration number - Business phone number Examples can include: - Certificate of incorporation - Business registration certificate - Government-issued business licence - Tax registration documents - Business bank statement - Utility or telephone bill issued to the business Use the documents Meta specifically requests from you. Most importantly, ensure the information is consistent. For example, if your incorporation document says: Acme Technologies Limited but your Meta Business Portfolio says: Acme Technology Ltd correct the discrepancy before submitting your verification where possible. 14. Submit and monitor Business Verification After providing the requested information, submit your application. Return to: Meta Business Suite → Settings → Security Center to monitor the status. Your status may appear as: - Not verified - Verification required - In review - Additional information required - Verified If Meta requests additional information, follow the instructions displayed in Business Suite rather than creating another Business Portfolio. 15. Review your WhatsApp account After setup, return to WhatsApp Manager and confirm that your business assets are correct. Check: - WhatsApp Business Account - Business phone number - Display name - Business profile - Display-name status - Account quality - Two-step verification - Business Verification status where available At this point, your Meta-side setup is ready for connection to a supported WhatsApp Business Platform integration. Understand the different verification statuses Several different Meta and WhatsApp statuses are often confused with one another. Phone number verified Meta has confirmed that your business controls the phone number. Business verified Meta has verified the organisation represented by your Business Portfolio. Display name approved WhatsApp has accepted the business display name associated with your phone number. Official Business Account An Official Business Account (OBA) is a separate WhatsApp status for eligible businesses. Creating a WABA and completing Meta Business Verification does not automatically give your business an Official Business Account badge. WhatsApp treats OBA status as a separate step businesses may consider as they scale their presence on the platform. You do not need an OBA badge simply to use an official WhatsApp Business Platform number. Keep your account compliant Setting up a WABA gives your business access to the official WhatsApp Business Platform, but businesses must continue following WhatsApp's policies. WhatsApp requires businesses to maintain accurate profile information and obtain appropriate customer consent before proactively messaging people. It can restrict access when businesses receive significant negative feedback or violate its policies. Before sending business messages, review: WhatsApp Business Messaging Policy WhatsApp Business Platform Onboarding Guide Setup checklist Before moving on to connecting your WhatsApp account to another platform, confirm that: - You have a Meta Business Portfolio for your organisation - Your legal business information is accurate - Your business website is live - Your business email is accessible - You have created or selected the correct WhatsApp Business Account - Your WhatsApp display name represents your business - Your business profile is complete - Your phone number has been added - You completed SMS or voice verification - Two-step verification is configured where required - Meta Business Verification has been completed or submitted where available - Your phone number appears correctly in WhatsApp Manager Useful Meta and WhatsApp links Meta Business Suite Create and manage your Business Portfolio and business assets. Open Meta Business Suite Meta Business Settings Manage people, WhatsApp accounts and other Meta business assets. Open Meta Business Settings WhatsApp Business Platform onboarding WhatsApp's official guide to getting started with the Business Platform. Read the official WhatsApp onboarding guide WhatsApp Business Messaging Policy Review WhatsApp's requirements for business messaging, customer consent and account quality. Read the WhatsApp Business Messaging Policy WhatsApp Business Platform onboarding PDF WhatsApp also provides a detailed onboarding guide covering account setup, verification and scaling. Open the WhatsApp Business Platform onboarding guide

How to Connect Ruut CSM with Instagram

Connect your Instagram Business account to Ruut and manage Instagram conversations alongside WhatsApp, Voice, Email, and every other customer channel—all from a single inbox. Before You Begin Before connecting your Instagram account, make sure you have: - An Instagram Professional (Business) account. - Administrator access to that Instagram account. - Administrator access to your Ruut workspace. - Permission to grant Meta the required messaging permissions. Note: Personal Instagram accounts cannot be connected. If you're currently using a personal account, switch it to a Business account before continuing. Connect Instagram to Ruut Step 1 Log in to your Ruut workspace. Navigate to: Settings → Workspace → Add Inbox Step 2 Select Instagram. Step 3 Click Continue with Instagram. A secure Meta authorization window will open. Step 4 Sign in using the Instagram Business account you want to connect. If you're already signed in, simply choose the correct account. Step 5 Review the permissions requested by Ruut. These permissions allow Ruut to: - Receive Instagram Direct Messages - Reply to customer conversations - Sync conversations in real time - Manage message status Click Allow to continue. Step 6 Once authorization is complete, Ruut will automatically connect your Instagram account. You can now: - Receive new Instagram messages - Reply from your shared team inbox - Assign conversations - Add notes - Use AI assistance - Track customer history - Collaborate with teammates Step 7 Choose which teammates should have access to the Instagram channel. You can always update channel permissions later. Click Finish Setup. You're All Set 🎉 Your Instagram Business account is now connected to Ruut. Whenever someone sends your business an Instagram Direct Message, it will instantly appear inside your Ruut Inbox, where your entire team can respond together. What You Can Do Next After connecting Instagram, you can: - Reply to Instagram DMs from Ruut - Assign conversations to teammates - Use AI to draft replies and summarize conversations - Add private notes - Track customer history across channels - Automate replies and workflows - Monitor team performance with analytics

How to Connect Facebook Messenger to Ruut

You can now connect your Facebook Page directly to Ruut to manage conversations, automate responses, and engage your audience—all in one place. Follow these steps to get started: Step 1: Go to the Workspace Section 1. From your Ruut dashboard, navigate to Settings → Workspaces. 2. Click Choose Channel to select the communication platform you want to integrate. Step 2: Select Messenger In the list of available channels, select Messenger. This tells Ruut that you want to connect your Facebook Messenger account. Step 3: Authenticate with Facebook 1. Once you select Messenger, you’ll see a “Connect Facebook” button. 2. Click it and sign in to your Facebook account. 3. Grant Ruut the necessary permissions to access your Page’s messages and manage conversations. Step 4: Finalize Your Workspace Setup After permission is granted: 1. Return to Ruut. 2. Select the workspace you just connected. 3. Re-enter your Workspace Name for confirmation. Your Facebook Messenger inbox is now live on Ruut! 4. Sent a message to your page to test the delivery of messages Important Notes - You must connect a Facebook Page account, not a personal profile. Ruut only integrates with Pages to comply with Meta’s business and privacy policies. - Ensure you have admin access to the Page before connecting. - If permissions are denied or partially granted, your Messenger inbox may not sync correctly.

Connect Ruut to your Website / Web applications

If you need to use live chat on a website, web application, or even a mobile application, you will need to create a website workspace. You can create as many website workspaces as you wish, and they will all be linked to one Ruut dashboard. Here is an integration guide on how to set up the website workspace on Ruut: Step 1: Connect from Dashboard On the dashboard, as a new user, you will see an option to set up your workspace. Click on it, and it will take you directly to the workspace section, where you will find a list of channels you can set up in your workspace. Step 2: Create a New Workspace From the workspace section on Ruut, you need to create a new workspace. Select the website workspace, and it will open up its requirements. Follow the steps provided. Step 3: Enter Necessary Information When you click on the website channel to connect to your workspace, you will need to submit several items: - Website Name: This is the name that will show on the Chat Widget. - Website Domain: This is the domain or web URL of the website or application you are integrating. - Blog URL: If you have a blog and want your users to read it directly from the chat widget, provide the link. The view will be rendered, allowing users to interact with it from the chat widget. - Widget Color: Set your company’s primary color as the widget color to match your brand and business. - Welcome Heading: This is the first text presented to your users when the chat widget is launched, e.g., "Welcome to Ruut Chat" or "Glad to have you join us here." - Welcome Tagline: This tagline accompanies the welcome heading, e.g., "Ask us anything." - Enable Greeting: If you want automated greetings when users first visit the chat widget, enable channel greeting. This will present another field where you can add a message for the greetings. After inputting all the necessary fields, click "Create Inbox" to save your details. Once saved, proceed to the next step. Step 4: Add Your Agent Once your website channel has been connected, add your support staff to that workspace. Once that’s done, you are ready to use your website channel with any application you wish. Step 5: Use Your Website Channel Now that your website channel is created, you will be presented with a view like the image below. For some applications you will be integrating with, you need to copy the entire script tag to the JavaScript section of your application. For mobile, WordPress, or other platforms, you will be required to copy the value of the Website token, which allows you to interact directly with the application. For Developers Identify a User (Set User Details) Once Ruut is ready, you can identify a user using the setUser method. This is optional but strongly recommended if your users are logged in. <script> window.addEventListener("ruut:ready", function () { window.$ruut.setUser("USER_ID", { email: "[email protected]", name: "John Doe", avatar_url: "https://example.com/avatar.png", phone_number: "+2348012345678", identifier_hash: "SECURE_HASH", description: "Premium customer", country_code: "NG", city: "Lagos", company_name: "Ruut Inc", social_profiles: { twitter: "johndoe", linkedin: "john-doe", facebook: "john.doe", github: "johndoe" } }); }); </script> Required vs Optional Fields Required - USER_ID A unique identifier for the user in your system (string). Common Optional Fields - email - name - avatar_url - phone_number Advanced / Optional Fields - identifier_hash (recommended for security) - description - country_code - city - company_name - social_profiles You can pass as many or as few fields as you need. Secure User Identity with identifier_hash For security-sensitive applications, Ruut supports identity verification using an identifier_hash. This hash should be generated on your server using your Ruut secret key and the user’s ID. It prevents impersonation and ensures user data integrity. If you don’t need this, you can safely omit it. Open the Chat Programmatically (Optional) If you want to open the chat automatically once Ruut is ready: <script> window.addEventListener("ruut:ready", function () { window.$ruut.toggle("open"); }); </script> Updating or Resetting a User Update Custom Attributes <script> window.$ruut.setCustomAttributes({ plan: "pro", last_login: "2026-01-10" }); </script> Remove a Custom Attribute <script> window.$ruut.deleteCustomAttribute("plan"); </script> Reset User Session <script> window.$ruut.reset(); </script> This is useful when a user logs out. Need more help with setting up your live chat workspace, speak to your account manager directly. Or reach us at [email protected]

How to Integrate Zoho Mail with Ruut Chat via IMAP

Integrating your Zoho Mail account with Ruut Chat, a customer communication platform, allows you to manage customer emails seamlessly within your unified inbox. Before connecting Zoho Mail to Ruut Chat using IMAP, ensure IMAP access is enabled in your Zoho Mail account. This guide walks you through the integration process with clear steps, visuals, and video support. ✅ Step 1: Enable IMAP Access in Zoho Mail IMAP access is disabled by default in Zoho Mail. Follow the steps below to enable it: 1. Log in to your Zoho Mail account. 2. Click the Settings (gear icon) in the top-right corner. 3. Go to Mail Accounts. 4. Select your primary email address. 5. Scroll to the IMAP section. 6. Check the box labeled IMAP Access. 7. (Optional) Enable: - Auto-Expunge Emails - Include Archived Emails - Folder configuration settings 8. Click Save. IMAP access Zoho IMAP Settings ✅ Step 2: Gather IMAP & SMTP Server Details Use the following settings for Zoho IMAP and SMTP when connecting to Ruut Chat: Setting Personal Zoho Mail Organization Zoho Mail IMAP Server imap.zoho.com imappro.zoho.com Port 993 993 SSL Yes Yes Username your Zoho email address your domain-based Zoho email ✅ Step 3: Add Zoho Mail as an Email Channel in Ruut Chat 1. Open your Ruut Chat dashboard. 2. Navigate to: Settings → Inboxes → Add Inbox. 3. Choose the Email channel. 4. Enter a name (e.g., “Support Email”). 5. Enable IMAP in the config tab. 6. Input the IMAP details: - Server: imap.zoho.com or imappro.zoho.com - Port: 993 - Username: Your Zoho email address - Password: Your Zoho password or app-specific password (if 2FA enabled) 7. Input SMTP details. 8. Test the connection by sending a test email and verifying it appears in Ruut Chat. 🔧 Troubleshooting & Notes - 2FA Users: Use an application-specific password for IMAP access. - Admin Permission: Org users may need admin rights to enable IMAP. - Free Plan Limits: Some free Zoho accounts may lack IMAP access. - Archived Email: Enable "Include Archived Emails" to sync them in Ruut Chat. 📋 Summary Step Action Enable IMAP in Zoho Settings → Mail Accounts → IMAP Access → Save Gather Server Info Refer to IMAP/SMTP table above Configure Ruut Chat Settings → Inboxes → Add Email → Input credentials Test Integration Verify email flow via test messages in Ruut Chat By following this guide, you can integrate your Zoho Mail inbox with Ruut Chat and streamline email communications within your support workflows.

Ruut Native Whatsapp API

# RUUT WhatsApp Proxy Service A comprehensive WhatsApp API service designed to connect RUUT.chat platform with WhatsApp messaging capabilities. This service provides a RESTful API to send various types of WhatsApp messages. ## Table of Contents - Overview - Onboarding - Authentication - API Endpoints - Health Check - Text Messages - Media Messages - PTV Messages - Audio Messages - Status/Story - Stickers - Location Messages - Contact Messages - Reactions - Poll Messages - List Messages - Button Messages - File Upload - Common Options - Error Handling - Development ## Overview The RUUT WhatsApp Proxy Service enables seamless integration between RUUT.chat platform and WhatsApp messaging. It allows you to send various types of WhatsApp messages including text, media, interactive elements, and more through a simple, unified API. ## Onboarding To use this service you need to have created an account with Ruut and obtained your api credentials. Base URL for this service is https://sentinel.ruut.chat ## Authentication All API endpoints (except health check) require authentication using the following headers: - access_token: Your RUUT access token - account_id: Your RUUT account ID - channel_id: Your RUUT channel/workspace ID These credentials are validated against the RUUT API for each request. ## API Endpoints ### Health Check GET /health Checks if the service is up and running. Response: { "status": "ok" } ### Text Messages POST /send-message/text Send a simple text message. Request Body: { "to": "1234567890", "text": "Hello from RUUT!", "options": { "delay": 1200, "linkPreview": false, "mentionsEveryOne": false, "mentioned": ["1234567890"] } } ### Media Messages POST /send-message/media Send media files (images, videos, documents). Request Body: { "to": "1234567890", "mediatype": "image", "mimetype": "image/jpeg", "caption": "Image caption", "media": "https://example.com/image.jpg", "fileName": "image.jpg", "options": { "delay": 1200 } } Supported mediatype values: - image: For images (jpg, png, etc.) - video: For video files - document: For documents (pdf, docx, etc.) ### PTV Messages POST /send-message/ptv Send Play-To-View video messages. Request Body: { "to": "1234567890", "video": "https://example.com/video.mp4", "options": { "delay": 1200 } } ### Audio Messages POST /send-message/audio Send narrated audio messages. Request Body: { "to": "1234567890", "audio": "https://example.com/audio.mp3", "options": { "delay": 1200, "encoding": true } } ### Status/Story POST /send-message/status Post status updates (WhatsApp stories). Request Body: { "type": "text", "content": "Hello, this is my status update!", "backgroundColor": "#008000", "font": 1, "allContacts": false, "statusJidList": ["[email protected]"] } ### Stickers POST /send-message/sticker Send sticker messages. Request Body: { "to": "1234567890", "sticker": "https://example.com/sticker.png", "options": { "delay": 1200 } } ### Location Messages POST /send-message/location Send location messages. Request Body: { "to": "1234567890", "name": "Location Name", "address": "Location Address", "latitude": -16.505538233564373, "longitude": -151.7422770494996, "options": { "delay": 1200 } } ### Contact Messages POST /send-message/contact Send contact cards. Request Body: { "to": "1234567890", "contact": [ { "fullName": "Contact Name", "wuid": "559999999999", "phoneNumber": "+55 99 9 9999-9999", "organization": "Company Name", "email": "[email protected]", "url": "https://example.com" } ], "options": { "delay": 1200 } } ### Reactions POST /send-message/reaction React to a message. Request Body: { "key": { "remoteJid": "[email protected]", "fromMe": true, "id": "MESSAGE_ID_TO_REACT_TO" }, "reaction": "🚀" } ### Poll Messages POST /send-message/poll Send poll messages for interactive feedback. Request Body: { "to": "1234567890", "name": "Poll Question", "selectableCount": 1, "values": [ "Option 1", "Option 2", "Option 3" ], "options": { "delay": 1200 } } ### List Messages POST /send-message/list Send interactive list messages. Request Body: { "to": "1234567890", "title": "List Title", "description": "List description", "buttonText": "Click Here", "footerText": "Footer text", "sections": [ { "title": "Section Title 1", "rows": [ { "title": "Option 1", "description": "Description for option 1", "rowId": "id1" }, { "title": "Option 2", "description": "Description for option 2", "rowId": "id2" } ] } ], "options": { "delay": 1200 } } ### Button Messages POST /send-message/buttons Send interactive button messages. Request Body: { "to": "1234567890", "title": "Button Title", "description": "Button Description", "footer": "Button Footer", "buttons": [ { "type": "reply", "displayText": "Button 1", "id": "button1" }, { "type": "url", "displayText": "Visit Website", "url": "https://example.com" }, { "type": "call", "displayText": "Call Us", "phoneNumber": "1234567890" } ], "options": { "delay": 1200 } } ### File Upload POST /upload-media Upload a file to be used in media messages. Request: - Content-Type: multipart/form-data - Include the file in the file field Response: { "success": true, "file": { "originalName": "example.jpg", "storedName": "1650123456789-example.jpg", "mimetype": "image/jpeg", "size": 123456, "url": "http://localhost:3000/uploads/1650123456789-example.jpg" } } You can then use the returned URL in media message requests. ## Common Options Most message endpoints support these common options: | Option | Type | Description | Default | |--------|------|-------------|---------| | delay | Number | Delay in milliseconds before sending the message | 0 | | mentionsEveryOne | Boolean | Whether to mention everyone in the group | false | | mentioned | Array | Array of phone numbers to mention | [] | ## Error Handling The API returns appropriate HTTP status codes: - 200 OK: Request successful - 400 Bad Request: Missing or invalid parameters - 401 Unauthorized: Invalid credentials - 500 Internal Server Error: Server error Error responses follow this format: { "error": "Error message", "details": "Additional error details" }

How to Set Up a WhatsApp Channel in Ruut

WhatsApp is one of the most popular messaging platforms worldwide, and integrating it with Ruut allows you to engage with your customers directly via WhatsApp within your Ruut account. This guide will walk you through the process of setting up a WhatsApp channel on Ruut, step by step. Prerequisites Before setting up your WhatsApp channel in Ruut, ensure the following: Ruut Account: You need to have a Ruut account. If you don't have one, sign up at Ruut. WhatsApp Business Account: You must have a verified WhatsApp Business account. If you don’t have one, you can set it up through the WhatsApp Business website. Twilio Account (Optional): If you are using Twilio as your SMS gateway for WhatsApp, you’ll need a Twilio account. Alternatively, you can use the official WhatsApp API via Facebook Business Manager. Phone Number: A valid phone number for WhatsApp communication. The number must be registered under your WhatsApp Business Account. API Access: If you plan to use WhatsApp API to integrate with Ruut, you will need API access either through Twilio or WhatsApp Business API directly. Step 1: Navigate to the Channels Section in Ruut. Log in to your Ruut account. In the left-hand sidebar, click on Settings (gear icon). From the settings menu, select Workspace Step 2: Add a New WhatsApp Channel Once you are in the Workspace section, click the Add Workspace button at the top right corner. In the “Add Workspace” screen, select WhatsApp from the available list of channels. Click Continue to proceed. Step 3: Choose Your WhatsApp Integration Method Ruut offers two ways to integrate WhatsApp: Option 1: Twilio API Integration If you are using Twilio to manage your WhatsApp messaging, select Twilio from the available options. Option 2: Official WhatsApp Business API If you are using the official WhatsApp Business API (through Facebook Business Manager), select WhatsApp Business API. Step 4: Configure the Channel Settings For Twilio Integration: 1. Account SID & Auth Token: ° Log into your Twilio account. ° Navigate to the Console page. ° Copy the Account SID and Auth Token from the dashboard. 2. Phone Number: ° Under your Twilio account, obtain the WhatsApp-enabled phone number (e.g., whatsapp:+1XXXXXXXXXX). ° Enter this phone number in the relevant field on the Ruut WhatsApp integration page. 3. Callback URL (Optional): ° Twilio requires a callback URL to handle incoming messages. If needed, provide the appropriate webhook URL here. 1. Click Save to connect Twilio to Ruut. For WhatsApp Business API Integration: 1. WhatsApp Business Account: ° You will need to input the WhatsApp Business Account ID associated with your WhatsApp Business API. This ID can be found in your Facebook Business Manager under the "WhatsApp" section. 2. Phone Number: ° Provide the WhatsApp Business phone number that is linked to your WhatsApp Business API. 3. API Token: ° You’ll need an API Token for authentication. Generate this token from the Facebook Developer portal for your WhatsApp Business API. 4. Webhook URL: ° Input the Webhook URL provided by Ruut for handling incoming messages. This URL should be set up in your Facebook Business Manager to forward messages to Ruut. 5. Click Save to complete the integration with WhatsApp Business API. Step 5: Verify and Test the WhatsApp Channel Once you’ve entered the necessary details for Twilio or WhatsApp Business API: 1. Verify the Phone Number: ° Ruut will automatically verify the WhatsApp phone number. You will receive a confirmation notification in your Ruut dashboard once the phone number is verified. ° If you don’t see a confirmation, double-check the details entered and retry the connection. 2. Test the Channel: ° Send a test message to the WhatsApp number you’ve integrated with Ruut from your phone or another WhatsApp account. ° Ensure that the message appears in your Ruut inbox. Step 6: Configure Additional Settings (Optional) 1. Channel Name: ° You can set a name for your WhatsApp channel to help identify it in the Ruut dashboard. ° Reply Templates: ° You can configure predefined WhatsApp templates (Quick Replies, Messages) for faster responses. 2. Business Hours: ° Set up business hours for when WhatsApp messages are expected to be answered by agents. Outside of business hours, Ruut can send automated responses. 3. Assign Agents: ° Assign specific agents or teams to handle incoming WhatsApp messages. This helps ensure that inquiries are directed to the right people. Step 7: Manage WhatsApp Messages in Ruut Once the integration is complete, you can start managing WhatsApp conversations directly from your Ruut inbox. Here’s how: 1. Incoming Messages: ° When a customer messages your WhatsApp number, the conversation will appear in your Ruut inbox. ° Agents can respond to messages, attach files, send media, and more, all from within the Ruut interface. 2. Message Tags: ° You can use tags to organize and categorize WhatsApp conversations (e.g., inquiries, issues, support). 3. Auto-Responses: ° Set up automated replies for out-of-office hours or during busy periods. These auto-responses can include a friendly message or let the customer know when they can expect a reply. Step 8: Troubleshooting Common Issues: 1. Connection Issues: ° If the WhatsApp channel does not connect properly, ensure that all API credentials (e.g., Twilio SID, Auth Token, WhatsApp Business API credentials) are correctly entered. ° Double-check the phone number format and ensure that it’s linked to the correct WhatsApp Business Account. 2. WhatsApp Messages Not Appearing: ° Ensure that the webhook is correctly configured for receiving incoming messages. ° Verify that the WhatsApp number is correctly verified in both the Ruut and Twilio/Facebook Business Manager dashboards. 3. Message Delays: ° If messages are delayed, check for issues with the API provider (Twilio or WhatsApp Business API). Sometimes, network issues or API throttling can affect the delivery speed. 4. Support: ° If you encounter any persistent issues, reach out to Ruut’s support team at [email protected] for assistance. Conclusion By following these steps, you should now have your WhatsApp channel successfully set up in Ruut. You can manage customer conversations, automate replies, and streamline your customer support directly from the Ruut interface. If you have any further questions or need help with the setup, don’t hesitate to contact Ruut support.