--- title: Superchat API Integration on Truto slug: superchat category: Helpdesk canonical: "https://truto.one/integrations/detail/superchat/" --- # Superchat API Integration on Truto **Category:** Helpdesk **Status:** Generally available ## Unified APIs ### Unified User Directory API - **Roles** — The Role object represents a role of a User. - **Users** — The User object represents a User. ### Unified Ticketing API - **Contacts** — Contact represent the external people you are in contact with. These could be customers, leads, etc. Contacts can be associated with an Account if the underlying product supports it. - **Tags** — Tags represent a common classification approach used in various ticketing systems. A Ticket may have one or more Tags associated with them. - **Users** — Users represent the people using the underlying ticketing system. They are usually called agents, team members, admins, etc. ## MCP-ready AI tools Truto exposes 48 tools for Superchat that AI agents can call directly. - **list_all_superchat_users** — List all users in Superchat workspace. Returns user fields including id, first_name, last_name, email, role, language, created_at, updated_at, and associated inboxes. - **get_single_superchat_user_by_id** — Get a specific user in Superchat. Requires id. Returns fields including id, first_name, last_name, email, role, language, created_at, updated_at, and inboxes the user has access to. - **list_all_superchat_me** — Get information about yourself as a Superchat user. Returns user.id, first_name, last_name, email, role, language, created_at, updated_at, inboxes, and workspace.name. - **list_all_superchat_contacts** — List all contacts in Superchat workspace. Returns an array of contact objects containing fields like id, first_name, last_name, gender, created_at, updated_at, handles, and custom_attributes. Results are sorted by created_at in descending order. - **get_single_superchat_contact_by_id** — Get a specific contact in Superchat using id. Returns id, first_name, last_name, gender, created_at, updated_at, handles, and custom_attributes for the contact. - **create_a_superchat_contact** — Create a new contact in Superchat using the required handles parameter. Returns the contact id, first_name, last_name, gender, created_at, updated_at, handles, and custom_attributes fields in the response. - **update_a_superchat_contact_by_id** — Update a contact in Superchat using id. Returns id, first_name, last_name, gender, created_at, updated_at, handles, and custom_attributes for the updated contact. - **delete_a_superchat_contact_by_id** — Delete a contact in Superchat using id. Returns the deleted contact's unique id in the response. - **list_all_superchat_channels** — List all channels in Superchat workspace. Returns an array of channel objects including id, name, type, inbox, and url. Results are sorted by created_at in descending order. - **get_single_superchat_channel_by_id** — Get a specific channel in Superchat by id. Returns fields such as id, name, type, inbox, and url for the channel. - **list_all_superchat_conversations** — List all conversations in Superchat. Returns an array of conversations with fields such as id, status, channel, contacts, assigned_users, labels, inbox, and time_window. - **get_single_superchat_conversation_by_id** — Get a conversation in Superchat using id. Returns id, url, channel details (type, id, url), status, snoozed_until, time_window, contacts, assigned_users, labels, and inbox details. - **update_a_superchat_conversation_by_id** — Update a conversation in Superchat using id. Returns id, status, channel details, assigned_users, labels, snoozed_until, time_window, contacts, and inbox details. - **delete_a_superchat_conversation_by_id** — Delete a conversation in Superchat using id. Returns the id of the deleted conversation confirming successful removal. - **get_single_superchat_conversation_export_by_id** — Get a conversation export in Superchat. Requires conversation_id and id. Returns id, start, end, link (url, valid_until), and status fields providing export details and a temporary download link. - **create_a_superchat_conversation_export** — Create a conversation export in Superchat. Requires conversation_id. Returns id, start, end, link (with url and valid_until), and status indicating the export job state. - **list_all_superchat_custom_attributes** — List all custom contact attributes in Superchat. Returns each attribute's id, name, resource, type, and specification for multi-select and single-select fields. - **list_all_superchat_files** — List all files in Superchat workspace. Returns an array of file objects sorted by created_at descendingly, including id, name, url, mime_type, and link with valid_until. - **get_single_superchat_file_by_id** — Get a file in Superchat using id. Returns file details including id, name, url, mime_type, and link (containing a temporary download url and valid_until timestamp). - **delete_a_superchat_file_by_id** — Delete a file in Superchat using the required id. Returns the id of the deleted file in the response. - **create_a_superchat_file** — Upload a new file to Superchat. Returns id (unique identifier), url (file API resource), name (file name), link.url (temporary download link), link.valid_until (link expiry time), and mime_type (file type). File size must not exceed 5MB. - **list_all_superchat_inboxes** — List all inboxes in Superchat. Returns fields including id, name, url, and users (each with id, email, and url). - **get_single_superchat_inbox_by_id** — Get a specific inbox in Superchat using id. Returns id, url, name, and users array with user id, url, and email for each user. - **list_all_superchat_labels** — List all labels in Superchat. Returns label id, name, and url for each conversation label available in the workspace. - **get_single_superchat_label_by_id** — Get a label in Superchat using id. Returns the label's id, name, and url fields representing the unique identifier, label name, and API resource URL respectively. - **create_a_superchat_message** — Send a message in Superchat using the specified channel (from) to a recipient (to). Returns id, url, created_at, updated_at, status, direction, to, from, content, in_reply_to, and conversation_id fields in the response. - **list_all_superchat_notes** — List all notes for a specific conversation in Superchat. Requires conversation_id. Returns id, content, created_at, updated_at, and author details for each note. - **get_single_superchat_note_by_id** — Get a specific note in Superchat using conversation_id and id. Returns note fields including id, content, created_at, updated_at, and author details (id, name, email, url). - **create_a_superchat_note** — Create a note in a specific conversation in Superchat. Requires conversation_id. Returns note id, url, created_at, updated_at, content, and author details including id, name, url, and email. - **update_a_superchat_note_by_id** — Update a note in Superchat for a specific conversation. Requires conversation_id and id. Returns the note's id, content, author details, and timestamps (created_at, updated_at). - **delete_a_superchat_note_by_id** — Delete a note in Superchat from a specific conversation using conversation_id and id. Returns the id of the deleted note in the response. - **list_all_superchat_templates** — List all templates in Superchat for a workspace. Returns an array of templates with fields such as id, name, status, content, created_at, updated_at, folder_id, and url. - **get_single_superchat_template_by_id** — Get a specific template in Superchat by id. Returns key fields including id, name, status, created_at, updated_at, folder_id, content, channels, and whats_app_business_account_id. - **delete_a_superchat_template_by_id** — Delete a template in Superchat using id. Returns the deleted template's id in the response. - **create_a_superchat_template** — Create a new template in Superchat workspace. Returns id, status, created_at, updated_at, folder_id, name, content details, channels, whats_app_business_account_id, and url in the response. - **update_a_superchat_template_by_id** — Update a template in Superchat using id. Updates the template name or moves it to a different folder. Returns id, status, name, folder_id, content, channels, created_at, and updated_at. - **list_all_superchat_template_folders** — List all template folders in Superchat. Returns each folder's id, name, and parent_id fields for identifying and organizing template folders. - **create_a_superchat_template_folder** — Create a template folder in Superchat. Requires name. Returns id, name, and parent_id of the created template folder. - **update_a_superchat_template_folder_by_id** — Update a specific template folder in Superchat using id. Returns id, name, and parent_id of the updated template folder. - **delete_a_superchat_template_folder_by_id** — Delete a specific template folder in Superchat. Requires id. Only empty folders can be deleted. Returns the id of the deleted folder in the response. - **list_all_superchat_contact_lists** — List all contact lists in Superchat. Returns a list of contact lists with fields id, name, and url for each contact list. - **get_single_superchat_contact_list_by_id** — Get a contact list in Superchat using id. Returns fields such as url (resource URL), id (contact list identifier), and name (contact list name). - **list_all_superchat_search_contacts** — Search contacts in Superchat by any field such as mail or phone using field, operator, and value. Returns contact objects with id, first_name, last_name, gender, handles, custom_attributes, created_at, and updated_at. - **list_all_superchat_contact_conversations** — Get all conversations for a specific contact in Superchat. Requires contact_id. Returns fields such as id, status, channel details, assigned_users, labels, and inbox information for each conversation. - **list_all_superchat_contact_contact_lists** — Get contact lists for a contact in Superchat. Requires contact_id. Returns each contact list with id (unique identifier), name (list name), and url (resource link). - **get_single_superchat_contact_contact_list_by_id** — Get a contact list for a contact in Superchat using contact_id and id. Returns fields url (resource URL), id (contact list identifier), and name (contact list name). - **delete_a_superchat_contact_contact_list_by_id** — Delete a contact from a specific contact list in Superchat. Requires contact_id and id. Returns the deleted contact list id upon success. - **create_a_superchat_contact_contact_list** — Add a contact to a single contact list in Superchat. Requires contact_id. Returns the contact list id, name, and url of the newly associated list. ## How it works 1. **Link your customer's Superchat account.** Use Truto's frontend SDK; we handle every OAuth and API key flow so you don't need to create the OAuth app. 2. **Authentication is automatic.** Truto refreshes tokens, stores credentials securely, and injects them into every API request. 3. **Call Truto's API to reach Superchat.** The Proxy API is a 1-to-1 mapping of the Superchat API. 4. **Get a unified response format.** Every response uses a single shape, with cursor-based pagination and data in the `result` field. ## Use cases - **Sync omnichannel chat history into your CRM** — CRM platforms can pull Superchat conversations, contacts, and custom attributes into their system so sales and support reps see a complete multi-channel communication timeline without leaving your product. - **Trigger WhatsApp transactional messages from your platform** — E-commerce, logistics, and booking platforms can look up approved WhatsApp templates and fire outbound messages through Superchat when order statuses change, appointments are confirmed, or deliveries are dispatched. - **Automate audience segmentation for WhatsApp campaigns** — Marketing automation and CDP tools can programmatically add or remove contacts from Superchat contact lists based on user behavior or lifecycle stage, enabling precise targeting for WhatsApp newsletter broadcasts. - **Enrich support threads with external system context** — SaaS platforms can push real-time events like payment failures or subscription changes as internal notes on Superchat conversations, giving agents immediate context without tab-switching. - **Export conversation transcripts for QA and compliance** — Agent coaching and compliance platforms can programmatically generate conversation exports from Superchat to analyze resolution quality, tone, and regulatory adherence at scale. ## What you can build - **Two-way contact sync with custom attributes** — Keep contacts and their custom fields in sync between your platform and Superchat using list, create, update, and delete operations on contacts and custom attributes. - **Automated WhatsApp template message dispatcher** — Let your users browse approved WhatsApp templates from Superchat and trigger compliant outbound messages directly from workflow automations in your product. - **Conversation timeline embedded in your UI** — Surface a chronological feed of Superchat conversations, labels, assigned agents, and notes directly on a contact or deal record inside your application. - **Dynamic contact list builder for campaign targeting** — Automatically manage Superchat contact list memberships based on segments defined in your platform, so marketing teams can launch targeted WhatsApp broadcasts without manual list curation. - **Internal note injector for cross-system context** — Push structured notes from your SaaS—like order updates, billing events, or AI-generated summaries—into specific Superchat conversation threads so agents have full context in real time. - **Conversation export pipeline for analytics** — Programmatically request and retrieve full conversation exports from Superchat to feed into your analytics, QA scoring, or compliance archiving workflows. ## FAQs ### What authentication method does the Superchat integration use? Superchat uses API key authentication. Truto handles credential storage and injection so your end users can connect their Superchat accounts securely without you managing keys directly. ### Which Unified APIs does the Superchat integration support? Superchat maps to the Unified User Directory API (Roles, Users) and the Unified Ticketing API (Contacts, Tags, Users). You can use these standardized schemas alongside Superchat-specific proxy endpoints for full coverage. ### Can I manage WhatsApp message templates through this integration? Yes. You can list all templates, retrieve individual templates by ID, create new templates, update existing ones, and delete them. You can also organize templates into folders using the template folder endpoints. ### Does the integration support sending outbound messages? Yes. The create_a_superchat_message tool lets you send outbound messages programmatically. For WhatsApp specifically, you need to reference an approved template, which you can look up via the templates endpoints. ### Can I manage contact list memberships programmatically? Yes. You can list a contact's list memberships, add a contact to a list, retrieve a specific membership, and remove a contact from a list—all through dedicated endpoints. This powers dynamic segmentation for campaigns. ### How does conversation export work? You create an export request using create_a_superchat_conversation_export for a specific conversation, then retrieve the export by ID. Superchat generates the export asynchronously and provides a temporary download URL for the full transcript.