Superchat

Getting the API key: in Superchat open Settings → Integrations → API (https://app.superchat.de/settings/integrations). Only workspace administrators see the key. Put it in SUPERCHAT_API_KEY; it is sent in the X-API-KEY header. The key has full read and write access to the workspace, so every user of this server can read all conversations and, with the send tools switched on, write to customers.

Rate limit: 2500 requests per 5 minutes per workspace, shared by all keys of that workspace. Above that Superchat answers 429 until the window resets.

Pagination: list tools return {url, results, pagination}. Pass pagination.next_cursor as after to get the next page and pagination.previous_cursor as before to go back. limit is 1 to 100 (default 20 for messages, 50 for templates).

Ids: every object has a string id with a type prefix. A channel id (from superchat_list_channels) is the sender of every message. Conversations come from superchat_list_conversations or, for one person, from superchat_search_contacts followed by superchat_list_contact_conversations.

Which tool to start with: superchat_get_me checks the key. To read a customer's thread: superchat_search_contacts (by e-mail, phone in E.164 format, or Instagram username) → superchat_list_contact_conversations → superchat_list_conversation_messages.

Sending rules (enforced by Meta, not by Superchat):

• WhatsApp: free text is delivered only within 24 hours of the contact's last inbound message. To write first, or later, send an approved WhatsApp template with superchat_send_template; superchat_get_conversation shows whether the time window is open. Templates are billed by Meta.
• Instagram and Facebook: replies only, within 7 days of the contact's last message. You cannot start a conversation.
• SMS and e-mail: no time window; you need the contact's consent. Sending to a new phone number or e-mail address creates a contact automatically.

Write tools: superchat_send_message, superchat_send_template and superchat_send_email reach customers and cannot be undone; they install switched off. superchat_create_contact, superchat_update_contact, superchat_update_conversation and superchat_create_note change the workspace. superchat_update_contact writes name and gender every time: read the contact first and pass the current values. Notes are internal and never sent.