# SmartChat API

> The SmartChat API and MCP server: send WhatsApp messages and manage contacts, templates, newsletters, automations and the landing page. English documentation. Every page is also available as Markdown (add .md).

Machine-readable: [OpenAPI (JSON)](https://docs.smartchat.marketing/openapi.json), [OpenAPI (YAML)](https://docs.smartchat.marketing/openapi.yaml), [Postman collection](https://docs.smartchat.marketing/postman-collection.json), [all pages in one file](https://docs.smartchat.marketing/llms-full.txt).

## Learn

### Start

- [SmartChat API](https://docs.smartchat.marketing/en/index.md): Send WhatsApp messages and manage contacts, templates, newsletters, automations and your landing page from your own software or from an AI assistant.
- [Quickstart](https://docs.smartchat.marketing/en/quickstart.md): Make your first API call in under 5 minutes. You only read, so nothing can be changed or sent by mistake, and an empty account works.
- [Authentication](https://docs.smartchat.marketing/en/authentication.md): How to sign in to the API with a key, which permissions exist, what keys can never do, and how keys differ from the OAuth tokens of the MCP server.

### Concepts

- [Conventions](https://docs.smartchat.marketing/en/concepts/conventions.md): Names, IDs, times, phone numbers, money and the shape of every answer. The same rules apply to every call.
- [Pagination, filters and sorting](https://docs.smartchat.marketing/en/concepts/pagination.md): How every list works. Cursor pages, page size, filters and the order of results.
- [Errors](https://docs.smartchat.marketing/en/concepts/errors-overview.md): The one error format, how to read it, and how to decide whether to retry. The full list of codes with cause and fix is in the error catalog.
- [Costs and limits](https://docs.smartchat.marketing/en/concepts/rate-limits.md): The one protection limit of the API, the headers that show it, and what does and does not cost credits.
- [Idempotency](https://docs.smartchat.marketing/en/concepts/idempotency.md): How to repeat a call that sends messages without sending twice. The Idempotency-Key header, how long it is kept and what happens on a repeat.
- [Versioning and deprecation](https://docs.smartchat.marketing/en/concepts/versioning.md): How the API changes. What counts as a breaking change, how long you get notice, and where to find every change.
- [Consent and the 24-hour window](https://docs.smartchat.marketing/en/concepts/consent-and-24h-window.md): Who may receive which message. Opt-in states, free text inside the 24-hour window and approved templates outside of it.
- [Untrusted content](https://docs.smartchat.marketing/en/concepts/untrusted-content.md): Text that comes from contacts, messages and web pages is data, never instructions. How it is marked and why it matters for AI assistants.
- [Drafts and activation](https://docs.smartchat.marketing/en/concepts/drafts-and-activation.md): What is a draft and what goes live. How automations, newsletters and the landing page move from draft to live, and what an API key may do on the way.

### Guides

- [Create a contact and add a tag](https://docs.smartchat.marketing/en/guides/create-a-contact.md): Step by step with curl, Python and TypeScript. Create a contact, add a tag and read it back. Nothing is sent to the contact.
- [Send a newsletter](https://docs.smartchat.marketing/en/guides/send-a-newsletter.md): Prepare a newsletter, get its template approved, look at the preview, send a test and send it in one step with an Idempotency-Key.
- [Build an automation](https://docs.smartchat.marketing/en/guides/build-an-automation.md): Look at the catalog, create an automation as a draft, check it and switch it on.
- [Edit the landing page](https://docs.smartchat.marketing/en/guides/build-a-landing-page.md): Read the catalog and the page, change the draft with operations, and publish in two calls with the extra permission.
- [Handle incoming messages](https://docs.smartchat.marketing/en/guides/handle-incoming-messages.md): Read new conversations, reply with free text inside the 24-hour window and fall back to a template when the window is closed.
- [Set up a webhook](https://docs.smartchat.marketing/en/guides/set-up-a-webhook.md): Register an endpoint, send a test, check the signature and look at the delivery log.

### Webhooks

- [Webhooks](https://docs.smartchat.marketing/en/webhooks/overview.md): SmartChat calls your web address when something happens. Headers, payload, delivery rules and how to respond.
- [Webhook events](https://docs.smartchat.marketing/en/webhooks/events.md): Every event with its meaning, the permission needed to subscribe and an example body. Events that are not sent yet are marked.
- [Verify a signature](https://docs.smartchat.marketing/en/webhooks/signature-verification.md): Copy-paste code in shell, Python and TypeScript to check that a webhook delivery comes from SmartChat. Includes replay protection and secret rotation.
- [Retries and health](https://docs.smartchat.marketing/en/webhooks/retries.md): What happens when your endpoint does not answer. The retry schedule, how an endpoint is paused and disabled, and how to get missed events back.
- [Webhook testing](https://docs.smartchat.marketing/en/webhooks/testing.md): Test a webhook endpoint without waiting for a real event, and find out why a delivery failed.
- [Webhook endpoints API](https://docs.smartchat.marketing/en/webhooks/endpoints-api.md): The calls to create, read, change and unsubscribe webhook endpoints, rotate secrets, test, replay and read deliveries.
- [Inbound webhooks](https://docs.smartchat.marketing/en/webhooks/inbound-webhooks.md): Start an automation from another app with a secret web address. How the address works, how to read it, and how duplicates are handled.

### Security

- [Sending safely](https://docs.smartchat.marketing/en/security.md): The checks the server makes before any message leaves, what keys can never do, and how to test without risk.

### More

- [Changelog](https://docs.smartchat.marketing/en/changelog.md): Every change to the API, newest first, with the kind of change.
- [Glossary](https://docs.smartchat.marketing/en/glossary.md): The words used in these docs, in simple terms, with a link to the page that explains each one.
- [Support and status](https://docs.smartchat.marketing/en/support.md): How to get help, what to send us, and where to check if the service has a problem.

## API reference

### Overview

- [API reference](https://docs.smartchat.marketing/en/api.md): Every call of the REST API, grouped by area, with permission, parameters, examples in curl, Python and TypeScript, and all possible errors.
- [Permissions](https://docs.smartchat.marketing/en/api/permissions.md): Every permission of a key, which level includes it, which need their own checkbox and which calls use it.
- [Error catalog](https://docs.smartchat.marketing/en/errors.md): Every error code with its status, cause, fix and whether you may retry. The links in error bodies (doc_url) lead here.
- [OpenAPI, Postman and other files](https://docs.smartchat.marketing/en/api/openapi.md): The machine-readable description of the API, the Postman collection, llms.txt and the Markdown version of every page.

### Reference: Account

- [Account](https://docs.smartchat.marketing/en/api/reference/account.md): The account overview.
- [Get opt-in status](https://docs.smartchat.marketing/en/api/reference/account/get_optin_status.md): Returns how many contacts are confirmed, pending, never asked or unsubscribed. Counts only, no personal data. Read-only.
- [Get account overview](https://docs.smartchat.marketing/en/api/reference/account/get_account_overview.md): Returns the account with parts chosen by include: setup, credits, optin and stats. Without include you get setup and credits. optin needs contacts:read and stats needs stats:read; plan and invoices are not included.

### Reference: AI reply

- [AI reply](https://docs.smartchat.marketing/en/api/reference/ai_reply.md): Settings and learned answers of the SmartChat AI reply.
- [Get AI reply settings](https://docs.smartchat.marketing/en/api/reference/ai_reply/get_ai_reply_settings.md): Returns the settings of the automatic AI reply: on or off, display name, instructions and the fixed questions and answers. Read-only; the notice that marks AI replies is always on. Use update_ai_reply_settings to change them.
- [Update AI reply settings](https://docs.smartchat.marketing/en/api/reference/ai_reply/update_ai_reply_settings.md): Changes the given settings of the automatic AI reply; all other settings stay as they are. Turning it on needs a plan that includes it and lets SmartChat answer your customers on its own; turning it off also cancels replies that are waiting to be sent. Returns all settings.
- [List learned answers](https://docs.smartchat.marketing/en/api/reference/ai_reply/list_learned_answers.md): Lists the latest 500 learned answers of the AI reply, newest first (older ones are not listed), with role, age and freshness. Read-only; switched-off answers are left out unless include_disabled is true. Use save_learned_answer to add or correct one.
- [Create learned answer](https://docs.smartchat.marketing/en/api/reference/ai_reply/create_learned_answer.md): Adds a question and the answer the AI should give. With role 'rule' (default) it changes the AI replies; with 'note' it is only stored, and the same pair twice only confirms the first one. Returns the answer.
- [Update learned answer](https://docs.smartchat.marketing/en/api/reference/ai_reply/update_learned_answer.md): Corrects, confirms or switches off a learned answer, or changes its role. Correcting the answer also confirms it, and there is no delete through the API: set disabled to true instead. Returns the answer.

### Reference: Automations

- [Automations](https://docs.smartchat.marketing/en/api/reference/automations.md): Automations, their catalog and their runs.
- [Get automation catalog](https://docs.smartchat.marketing/en/api/reference/automations/get_automation_catalog.md): Returns every trigger and step type an automation can use, with fields, limits and rules. Read it before create_automation. The catalog only lists what runs today.
- [List automations](https://docs.smartchat.marketing/en/api/reference/automations/list_automations.md): Lists the automations of the account, newest first. Filter by status or trigger. Use get_automation for the steps and the latest runs.
- [Get automation](https://docs.smartchat.marketing/en/api/reference/automations/get_automation.md): Returns one automation with trigger, steps, rules and hints. Add include=runs for the latest runs. Webhook addresses and header values show as *** unless the key has hooks:read_secret.
- [Create automation](https://docs.smartchat.marketing/en/api/reference/automations/create_automation.md): Creates an automation. Without status it is a draft and never runs; status active runs it at once and needs the permission automations:run. Steps that call an address need webhooks:write, steps in connected apps need connections:run.
- [Update automation](https://docs.smartchat.marketing/en/api/reference/automations/update_automation.md): Changes name, trigger, steps or rules of an automation. Send only what changes; a list of steps replaces the whole list (keep the step ids). On an active automation this needs automations:run.
- [Set automation status](https://docs.smartchat.marketing/en/api/reference/automations/set_automation_status.md): Sets the status to draft, active or paused. Active needs automations:run; draft is refused once the automation was active, because it would remove waiting messages (use paused). Templates not approved yet are listed in notices.
- [List automation runs](https://docs.smartchat.marketing/en/api/reference/automations/list_automation_runs.md): Lists the runs of one automation, newest first. Filter by status. Each run says whether the event matched, the flow was started, a rule skipped it or it failed.
- [Start automation run](https://docs.smartchat.marketing/en/api/reference/automations/create_automation_run.md): Starts an active automation of the trigger type api_call for one contact. Call it without plan_id for the preview, then with the plan_id and a different Idempotency-Key. If the start fails, the plan stays valid.
- [Get inbound webhook](https://docs.smartchat.marketing/en/api/reference/automations/get_inbound_webhook.md): Returns the secret inbound address of an automation that starts from outside, and its filters. Anyone with the address can start the automation, so it needs the permission hooks:read_secret.

### Reference: Billing

- [Billing](https://docs.smartchat.marketing/en/api/reference/billing.md): Plan, invoices and credit history (read only).
- [Get billing overview](https://docs.smartchat.marketing/en/api/reference/billing/get_billing.md): Returns the current plan, the subscription state, the credit balance and whether a payment is open. Read-only. Changing the plan or paying is only possible in the app.
- [List invoices](https://docs.smartchat.marketing/en/api/reference/billing/list_invoices.md): Lists the stored invoices of the account, newest first, with number, amount, currency and status. Read-only. The PDF files can only be downloaded in the app.
- [List credit history](https://docs.smartchat.marketing/en/api/reference/billing/list_credit_history.md): Lists the latest 200 credit bookings of the account, newest first (older bookings are not listed), with the kind of booking and the time. Read-only. It shows no amounts; the balance is in get_billing.

### Reference: Business profile

- [Business profile](https://docs.smartchat.marketing/en/api/reference/business_profile.md): The business profile.
- [Get business profile](https://docs.smartchat.marketing/en/api/reference/business_profile/get_business_profile.md): Returns the business profile of the account: name, description, address, websites, brand, test number, template style, content rules and the legal page addresses. Read-only. Use update_business_profile to change it.
- [Update business profile](https://docs.smartchat.marketing/en/api/reference/business_profile/update_business_profile.md): Changes the given fields of the business profile; all other fields stay as they are. Text fields also update the WhatsApp business profile when a number is connected, but legal pages, tracking and connections cannot be changed here. Returns the whole profile.

### Reference: Connection and apps

- [Connection and apps](https://docs.smartchat.marketing/en/api/reference/meta.md): Connection check and connected apps.
- [Get current connection](https://docs.smartchat.marketing/en/api/reference/meta/get_me.md): Returns the account, the API key or connection and the permissions used for this call. Use it to test a connection or to see which permissions a key has. Read-only; no side effects.
- [List events](https://docs.smartchat.marketing/en/api/reference/meta/list_events.md): Lists past events of one type, newest first, so a tool can poll for new ones. Needs inbox:read, and also contacts:read for contact.opted_out. Read-only; webhooks push the same events without polling.

### Reference: Contacts

- [Contacts](https://docs.smartchat.marketing/en/api/reference/contacts.md): People you can message: contacts, tags, opt-in state.
- [Search contacts](https://docs.smartchat.marketing/en/api/reference/contacts/search_contacts.md): Finds contacts by name, phone number or email (partial match), and filters by tag, opt-in status or creation time. Returns one page, newest first, with a cursor for the next page. Use get_contact for one contact.
- [Get contact](https://docs.smartchat.marketing/en/api/reference/contacts/get_contact.md): Returns one contact with its tags, opt-in status and creation time. Use search_contacts to find the contact ID first. Read-only.
- [Create contact](https://docs.smartchat.marketing/en/api/reference/contacts/create_contact.md): Creates a contact from a phone number or an email; the opt-in status starts as none and only the contact can confirm it. Needs an Idempotency-Key header. Returns the contact or contact_already_exists with existing_id.
- [Update contact](https://docs.smartchat.marketing/en/api/reference/contacts/update_contact.md): Changes the name, phone number or email of a contact and sends no message. A new phone number resets the opt-in status to none, because the old consent does not apply to it. Returns the contact.
- [List tags](https://docs.smartchat.marketing/en/api/reference/contacts/list_tags.md): Lists all tags in the account with the number of contacts for each, sorted by name. Use the names as filter in search_contacts or in tag_contacts. Read-only.
- [Tag contacts](https://docs.smartchat.marketing/en/api/reference/contacts/tag_contacts.md): Adds tags to up to 100 contacts and removes tags from them; removing a tag never deletes the contact. System tags cannot be set or removed. Needs an Idempotency-Key header; returns one result per distinct contact ID, and one failed contact does not stop the others.
- [Unsubscribe contact](https://docs.smartchat.marketing/en/api/reference/contacts/unsubscribe_contact.md): Unsubscribes a contact with a confirmed opt-in from all marketing messages and sends no message. It cannot be undone through the API; only the contact can sign up again. Needs an Idempotency-Key header and returns the contact.
- [Create contact export](https://docs.smartchat.marketing/en/api/reference/contacts/create_contact_export.md): Stores a copy of the contacts that match the filters (names, numbers, emails) for 24 hours, ready when the call returns; read the rows with get_contact_export. Sends nothing and changes no contact. Needs an Idempotency-Key header.
- [Get contact export](https://docs.smartchat.marketing/en/api/reference/contacts/get_contact_export.md): Returns a contact export with one page of its rows; use cursor for the next page. Exports are removed 24 hours after creation. Read-only.
- [Create opt-in confirmations](https://docs.smartchat.marketing/en/api/reference/contacts/create_optin_confirmations.md): Sends the opt-in confirmation message by WhatsApp to chosen contacts who have not confirmed yet. Call without plan_id for a preview, then again with the plan_id and a new Idempotency-Key. Returns the preview or the queued count.

### Reference: Conversations

- [Conversations](https://docs.smartchat.marketing/en/api/reference/conversations.md): Conversations and messages in the inbox.
- [List conversations](https://docs.smartchat.marketing/en/api/reference/conversations/list_conversations.md): Lists the inbox conversations, newest message first, with the last message and the unread count. Filters by contact, unread state and a search word. Use get_conversation for the messages of one conversation.
- [Get conversation](https://docs.smartchat.marketing/en/api/reference/conversations/get_conversation.md): Returns one conversation and, with include=messages, its last 20 messages in time order. Use list_messages with conversation_id for older messages. Read-only.
- [List messages](https://docs.smartchat.marketing/en/api/reference/conversations/list_messages.md): Lists messages across the account or of one conversation, newest first. Filters by direction and time. Use it to poll for new inbound messages.
- [Update conversation](https://docs.smartchat.marketing/en/api/reference/conversations/update_conversation.md): Marks a conversation as read by setting its unread count to zero. Sends nothing and changes no message. Returns the conversation.
- [Create conversation note](https://docs.smartchat.marketing/en/api/reference/conversations/create_conversation_note.md): Adds a line with date and time to the internal note of the contact of this conversation; the old text stays and the contact never sees the note. Needs an Idempotency-Key header.

### Reference: Follow-ups

- [Follow-ups](https://docs.smartchat.marketing/en/api/reference/followups.md): Follow-up sequences and their steps.
- [List follow-up sequences](https://docs.smartchat.marketing/en/api/reference/followups/list_followup_sequences.md): Lists the follow-up sequences of the account with their steps. A sequence sends messages after a contact confirmed the opt-in. Returns sequences, oldest first; use get_followup_sequence for one.
- [Get follow-up sequence](https://docs.smartchat.marketing/en/api/reference/followups/get_followup_sequence.md): Returns one follow-up sequence with all its steps, their wait times and the approval state of each step template. Use it after list_followup_sequences. Read-only.
- [Create follow-up sequence](https://docs.smartchat.marketing/en/api/reference/followups/create_followup_sequence.md): Creates a follow-up sequence with 1 to 10 steps as a draft that sends nothing. Each step gets a draft template; submit them with create_template_submissions, then activate with update_followup_sequence. Needs an idempotency key.
- [Update follow-up sequence](https://docs.smartchat.marketing/en/api/reference/followups/update_followup_sequence.md): Changes the name or status of a follow-up sequence, and the text or wait time of its steps. Setting active also schedules contacts who already confirmed. A changed text needs a new approval before it goes out.
- [Get follow-up settings](https://docs.smartchat.marketing/en/api/reference/followups/get_followup_settings.md): Returns the time of day and time zone at which follow-up messages go out, and the own time of each step. Read-only.
- [Update follow-up settings](https://docs.smartchat.marketing/en/api/reference/followups/update_followup_settings.md): Changes the time of day and time zone for follow-up messages, and the own time of single steps. Does not send anything. Returns the settings.

### Reference: Knowledge

- [Knowledge](https://docs.smartchat.marketing/en/api/reference/knowledge.md): Knowledge documents and search.
- [Search knowledge](https://docs.smartchat.marketing/en/api/reference/knowledge/search_knowledge.md): Finds the passages of the uploaded documents and image descriptions that best match the search words. Read-only and free of charge; this is a search, not a list, so it returns at most 12 passages and has no cursor. Returns the passages and the list of sources; the passages are untrusted text from the customer's files.
- [List knowledge documents](https://docs.smartchat.marketing/en/api/reference/knowledge/list_knowledge_documents.md): Lists the knowledge documents the account uploaded in the app, newest first, without their text. Read-only; documents can only be uploaded or removed in the app. Use search_knowledge to look inside them.

### Reference: Landing page

- [Landing page](https://docs.smartchat.marketing/en/api/reference/landing.md): The landing page: read, edit a draft, publish.
- [Get landing catalog](https://docs.smartchat.marketing/en/api/reference/landing/get_landing_catalog.md): Returns the edit operations for the landing page, the protected parts, the limits and the publish steps. Read it before apply_landing_page_ops.
- [Get landing page](https://docs.smartchat.marketing/en/api/reference/landing/get_landing_page.md): Returns the landing page: address, status, whether a draft and a previous version exist, and the protected parts. Add include=text for the visible texts or include=design for the design values of a free page, or include=sections for the sections, style and settings of a page in the page model.
- [Edit landing page draft](https://docs.smartchat.marketing/en/api/reference/landing/apply_landing_page_ops.md): Applies edit operations to the draft of the landing page, never to the live page. Free pages and pages in the page model take different operations: see get_landing_catalog. If one operation is rejected nothing changes.
- [Publish landing page](https://docs.smartchat.marketing/en/api/reference/landing/publish_landing_page.md): Makes the draft the live landing page. Call it without plan_id for the preview and the checks, then again with the plan_id. The page is never offline; the old version can be restored.
- [Restore previous landing page](https://docs.smartchat.marketing/en/api/reference/landing/restore_landing_page.md): Puts the version from before the last publication into the draft. The live page does not change until you publish. An unpublished draft is replaced for good, so it needs discard_draft true.

### Reference: Media

- [Media](https://docs.smartchat.marketing/en/api/reference/media.md): The media library.
- [List media](https://docs.smartchat.marketing/en/api/reference/media/list_media.md): Lists the files in the media library, newest first, without chat attachments, proof documents and knowledge files. Read-only. Use upload_file to add a file.
- [Upload media file](https://docs.smartchat.marketing/en/api/reference/media/create_media.md): Adds a file to the media library from multipart field 'file', from an address ('url') or from base64 data, with the same checks as in the app. Uses no credits. Returns the media object; an identical image that already exists is returned instead.

### Reference: Newsletters

- [Newsletters](https://docs.smartchat.marketing/en/api/reference/newsletters.md): Newsletters: drafts, previews, sending and tests.
- [List newsletters](https://docs.smartchat.marketing/en/api/reference/newsletters/list_newsletters.md): Lists the newsletters of the account, newest first. Use it to find a newsletter ID and its state. Returns newsletters with status, audience, template state and whether they are ready to send.
- [Get newsletter](https://docs.smartchat.marketing/en/api/reference/newsletters/get_newsletter.md): Returns one newsletter with its text, audience, template state and send state. Use it to follow a send: the status moves from sending to completed. Read-only.
- [Create newsletter](https://docs.smartchat.marketing/en/api/reference/newsletters/create_newsletter.md): Creates a newsletter as a draft with its own template. Nothing is sent: submit the template with create_template_submissions, then call send_newsletter. Needs an idempotency key and returns the newsletter.
- [Update newsletter](https://docs.smartchat.marketing/en/api/reference/newsletters/update_newsletter.md): Changes the title, text, language, button or audience of a newsletter draft. Scheduled or sent newsletters are locked: cancel the schedule first with control_newsletter. Changing the text creates a new template version that needs approval.
- [Preview newsletter send](https://docs.smartchat.marketing/en/api/reference/newsletters/get_newsletter_send_preview.md): Calculates who would receive a newsletter, now or at a given time, and whether sending would be accepted. Nothing is sent and nothing is saved. Use it before send_newsletter.
- [Send newsletter](https://docs.smartchat.marketing/en/api/reference/newsletters/send_newsletter.md): Sends a newsletter now, or schedules it, to every contact with a confirmed opt-in inside its audience; unsubscribed contacts never receive it. Needs an approved template and an idempotency key. Sending cannot be undone once started.
- [Control newsletter send](https://docs.smartchat.marketing/en/api/reference/newsletters/control_newsletter.md): Cancels a scheduled newsletter, pauses a running one or resumes a paused or failed one. Messages already delivered stay delivered, and resuming reaches only contacts who did not get it yet. Needs an idempotency key.
- [Send test newsletter](https://docs.smartchat.marketing/en/api/reference/newsletters/send_test_newsletter.md): Sends one test message of a newsletter to a single phone number, never to a contact who unsubscribed. Needs an approved template and an idempotency key. Leave out 'to' to use the test number of the account.

### Reference: Sends

- [Sends](https://docs.smartchat.marketing/en/api/reference/sends.md): Single messages (free text inside the 24-hour window, or approved templates) and their status.
- [Send text message](https://docs.smartchat.marketing/en/api/reference/sends/send_text_message.md): Sends a free text message to one contact by WhatsApp as a reply. It only works while the 24-hour window of the contact is open; otherwise it fails with window_closed and a template must be used. Needs an Idempotency-Key header.
- [Send template message](https://docs.smartchat.marketing/en/api/reference/sends/send_template_message.md): Sends an approved template to one contact with a confirmed opt-in by WhatsApp, also outside the 24-hour window. Fills the template variables from the contact and from variables. Needs an Idempotency-Key header.
- [Get send](https://docs.smartchat.marketing/en/api/reference/sends/get_send.md): Returns the state of one single send: queued, sent, delivered, read, failed or skipped, with the reason if it failed. Use the id from send_text_message or send_template_message. Read-only.

### Reference: Statistics

- [Statistics](https://docs.smartchat.marketing/en/api/reference/stats.md): Statistics without personal data.
- [Get statistics](https://docs.smartchat.marketing/en/api/reference/stats/get_stats.md): Returns send, delivery and read numbers, new contacts and the top sends for 7, 30 or 90 days. Contains no personal data. Read-only.

### Reference: Team

- [Team](https://docs.smartchat.marketing/en/api/reference/team.md): Team members (read only).
- [List team members](https://docs.smartchat.marketing/en/api/reference/team/list_team_members.md): Lists the members of the team of the account with name, role and status, oldest first. Read-only. Inviting people, changing roles and removing members are only possible in the app.

### Reference: Templates

- [Templates](https://docs.smartchat.marketing/en/api/reference/templates.md): WhatsApp message templates.
- [List templates](https://docs.smartchat.marketing/en/api/reference/templates/list_templates.md): Lists the WhatsApp message templates of the account, newest first. Use it to find a template ID and to see which templates WhatsApp has approved. Returns templates with status, variables and whether they can be sent.
- [Get template](https://docs.smartchat.marketing/en/api/reference/templates/get_template.md): Returns one WhatsApp message template with its text, buttons, approval state and the rule violations that block a submission. Use it after list_templates. Read-only.
- [Create template](https://docs.smartchat.marketing/en/api/reference/templates/create_template.md): Creates a WhatsApp message template as a draft. Nothing goes to WhatsApp until you submit it with create_template_submissions. Needs an idempotency key and returns the template.
- [Update template](https://docs.smartchat.marketing/en/api/reference/templates/update_template.md): Changes the text, language, footer or buttons of a template. An approved template keeps sending its approved version until the new version is submitted and approved. Returns the template.
- [Submit templates](https://docs.smartchat.marketing/en/api/reference/templates/create_template_submissions.md): Submits template drafts to WhatsApp for approval. Call without plan_id for a preview of what would be submitted, then again with the plan_id. Sends nothing to contacts; WhatsApp decides within a few minutes to 24 hours.

### Reference: Webhook endpoints

- [Webhook endpoints](https://docs.smartchat.marketing/en/api/reference/webhooks.md): Outgoing webhook endpoints, deliveries and tests.
- [Create webhook endpoint](https://docs.smartchat.marketing/en/api/reference/webhooks/create_webhook_endpoint.md): Creates an outgoing webhook endpoint that receives the chosen events at an HTTPS address. Sends no messages to contacts. Returns the endpoint with its signing secret, shown only once; use it to verify every delivery.
- [List webhook endpoints](https://docs.smartchat.marketing/en/api/reference/webhooks/list_webhook_endpoints.md): Lists the outgoing webhook endpoints of the account, newest first. Does not show signing secrets, only the last 4 characters. Use get_webhook_endpoint for one endpoint or list_webhook_deliveries for its log.
- [Get webhook endpoint](https://docs.smartchat.marketing/en/api/reference/webhooks/get_webhook_endpoint.md): Reads one outgoing webhook endpoint with its status and failure counter. Does not show the signing secret. Use list_webhook_deliveries to see single deliveries.
- [Update webhook endpoint](https://docs.smartchat.marketing/en/api/reference/webhooks/update_webhook_endpoint.md): Changes the address, the note or the subscribed events of a webhook endpoint. Sends no messages and keeps the signing secret. Send only the fields that change.
- [Unsubscribe webhook endpoint](https://docs.smartchat.marketing/en/api/reference/webhooks/unsubscribe_webhook_endpoint.md): Removes a webhook endpoint and its delivery log, so no more events are sent to it. This is the only deletion allowed with an API key in this area. Sends no messages to contacts.
- [Rotate webhook secret](https://docs.smartchat.marketing/en/api/reference/webhooks/rotate_webhook_secret.md): Creates a new signing secret for an endpoint. During grace_hours (0 to 72, default 24) every delivery carries two signatures, so you can switch without losing events. Returns the new secret, shown only once.
- [Enable webhook endpoint](https://docs.smartchat.marketing/en/api/reference/webhooks/enable_webhook_endpoint.md): Switches a paused or disabled webhook endpoint back to active and resets its failure counter. With replay_since it also queues the events of that time again (up to 7 days). Sends no messages.
- [Test webhook endpoint](https://docs.smartchat.marketing/en/api/reference/webhooks/test_webhook_endpoint.md): Sends one signed webhook.test event to the endpoint and waits for the answer. Sends no messages to contacts and does not change the endpoint health. Returns the HTTP status and the duration.
- [Replay webhook events](https://docs.smartchat.marketing/en/api/reference/webhooks/replay_webhook_events.md): Queues the events since a given time (at most 7 days back, at most 10000 events) for delivery to this endpoint again. Only events the endpoint subscribes to are queued. Requires an Idempotency-Key and sends no messages to contacts.
- [List webhook deliveries](https://docs.smartchat.marketing/en/api/reference/webhooks/list_webhook_deliveries.md): Lists the deliveries of one endpoint, newest first, kept for 30 days. Each entry shows the attempt count, status, HTTP status and a short error. Filter by status to find failures.
- [Redeliver webhook delivery](https://docs.smartchat.marketing/en/api/reference/webhooks/redeliver_webhook_delivery.md): Queues the event of an earlier delivery for another delivery to the same endpoint, while the event is in the 30 day log and the endpoint is active. Sends no messages to contacts. Returns the new delivery.

## MCP

### Start

- [MCP server](https://docs.smartchat.marketing/en/mcp.md): Let an AI assistant such as Claude or ChatGPT use SmartChat. What the MCP server is, how it signs in, what it can and cannot do.
- [Connect Claude](https://docs.smartchat.marketing/en/mcp/setup-claude.md): Add the SmartChat MCP server to Claude, choose permissions, test the connection and fix problems.
- [Connect ChatGPT](https://docs.smartchat.marketing/en/mcp/setup-chatgpt.md): Add the SmartChat MCP server to ChatGPT, choose permissions and test the connection.
- [Zapier, Make and n8n](https://docs.smartchat.marketing/en/mcp/setup-zapier-make-n8n.md): Use SmartChat with Zapier, Make and n8n today with the REST API and webhooks. Listings in their app directories are not available yet.
- [Rules for agents, resources and prompts](https://docs.smartchat.marketing/en/mcp/prompts-and-resources.md): What an AI assistant should know before it uses SmartChat, and what the server offers besides tools.
- [MCP security](https://docs.smartchat.marketing/en/mcp/security.md): What protects you when an AI assistant uses SmartChat. Permissions, server checks, untrusted text and how to cut access.
- [Tools](https://docs.smartchat.marketing/en/mcp/tools.md): Every tool of the MCP server with its permission and effect. Each tool has a page with its input and its hints.
- [REST to MCP](https://docs.smartchat.marketing/en/mcp/rest-coverage.md): Which REST operations an AI assistant can use through MCP, and which are REST only. Built from the same register as the API reference.

### Tools

- [add_conversation_note](https://docs.smartchat.marketing/en/mcp/tools/add_conversation_note.md): Adds a line with date and time to the internal note of the contact of this conversation; the old text stays and the contact never sees the note.
- [apply_landing_page_ops](https://docs.smartchat.marketing/en/mcp/tools/apply_landing_page_ops.md): Applies edit operations to the draft of the landing page, never to the live page. Free pages and pages in the page model take different operations: see get_landing_catalog. If one operation is rejected nothing changes.
- [control_newsletter](https://docs.smartchat.marketing/en/mcp/tools/control_newsletter.md): Cancels a scheduled newsletter, pauses a running one or resumes a paused or failed one. Messages already delivered stay delivered, and resuming reaches only contacts who did not get it yet.
- [export_contacts](https://docs.smartchat.marketing/en/mcp/tools/export_contacts.md): Stores a copy of the contacts that match the filters (names, numbers, emails) for 24 hours, ready when the call returns; read the rows with get_contact_export. Sends nothing and changes no contact.
- [get_account_overview](https://docs.smartchat.marketing/en/mcp/tools/get_account_overview.md): Returns the account with parts chosen by include: setup, credits, optin and stats. Without include you get setup and credits. optin needs contacts:read and stats needs stats:read; plan and invoices are not included.
- [get_ai_reply_settings](https://docs.smartchat.marketing/en/mcp/tools/get_ai_reply_settings.md): Returns the settings of the automatic AI reply: on or off, display name, instructions and the fixed questions and answers. Read-only; the notice that marks AI replies is always on. Use update_ai_reply_settings to change them.
- [get_automation](https://docs.smartchat.marketing/en/mcp/tools/get_automation.md): Returns one automation with trigger, steps, rules and hints. Add include=runs for the latest runs. Webhook addresses and header values show as *** unless the key has hooks:read_secret.
- [get_automation_catalog](https://docs.smartchat.marketing/en/mcp/tools/get_automation_catalog.md): Returns every trigger and step type an automation can use, with fields, limits and rules. Read it before create_automation. The catalog only lists what runs today.
- [get_business_profile](https://docs.smartchat.marketing/en/mcp/tools/get_business_profile.md): Returns the business profile of the account: name, description, address, websites, brand, test number, template style, content rules and the legal page addresses. Read-only. Use update_business_profile to change it.
- [get_contact](https://docs.smartchat.marketing/en/mcp/tools/get_contact.md): Returns one contact with its tags, opt-in status and creation time. Use search_contacts to find the contact ID first. Read-only.
- [get_conversation](https://docs.smartchat.marketing/en/mcp/tools/get_conversation.md): Returns one conversation and, with include=messages, its last 20 messages in time order. Use list_messages with conversation_id for older messages. Read-only.
- [get_landing_catalog](https://docs.smartchat.marketing/en/mcp/tools/get_landing_catalog.md): Returns the edit operations for the landing page, the protected parts, the limits and the publish steps. Read it before apply_landing_page_ops.
- [get_landing_page](https://docs.smartchat.marketing/en/mcp/tools/get_landing_page.md): Returns the landing page: address, status, whether a draft and a previous version exist, and the protected parts. Add include=text for the visible texts or include=design for the design values of a free page, or include=sections for the sections, style and settings of a page in the page model.
- [get_newsletter](https://docs.smartchat.marketing/en/mcp/tools/get_newsletter.md): Returns one newsletter with its text, audience, template state and send state. Use it to follow a send: the status moves from sending to completed. Read-only.
- [get_send_status](https://docs.smartchat.marketing/en/mcp/tools/get_send_status.md): Returns the state of one single send: queued, sent, delivered, read, failed or skipped, with the reason if it failed. Use the id from send_text_message or send_template_message. Read-only.
- [list_automation_runs](https://docs.smartchat.marketing/en/mcp/tools/list_automation_runs.md): Lists the runs of one automation, newest first. Filter by status. Each run says whether the event matched, the flow was started, a rule skipped it or it failed.
- [list_automations](https://docs.smartchat.marketing/en/mcp/tools/list_automations.md): Lists the automations of the account, newest first. Filter by status or trigger. Use get_automation for the steps and the latest runs.
- [list_conversations](https://docs.smartchat.marketing/en/mcp/tools/list_conversations.md): Lists the inbox conversations, newest message first, with the last message and the unread count. Filters by contact, unread state and a search word. Use get_conversation for the messages of one conversation.
- [list_followup_sequences](https://docs.smartchat.marketing/en/mcp/tools/list_followup_sequences.md): Lists the follow-up sequences of the account with their steps. A sequence sends messages after a contact confirmed the opt-in. Returns sequences, oldest first; use get_followup_sequence for one.
- [list_knowledge_documents](https://docs.smartchat.marketing/en/mcp/tools/list_knowledge_documents.md): Lists the knowledge documents the account uploaded in the app, newest first, without their text. Read-only; documents can only be uploaded or removed in the app. Use search_knowledge to look inside them.
- [list_learned_answers](https://docs.smartchat.marketing/en/mcp/tools/list_learned_answers.md): Lists the latest 500 learned answers of the AI reply, newest first (older ones are not listed), with role, age and freshness. Read-only; switched-off answers are left out unless include_disabled is true. Use save_learned_answer to add or correct one.
- [list_media](https://docs.smartchat.marketing/en/mcp/tools/list_media.md): Lists the files in the media library, newest first, without chat attachments, proof documents and knowledge files. Read-only. Use upload_file to add a file.
- [list_newsletters](https://docs.smartchat.marketing/en/mcp/tools/list_newsletters.md): Lists the newsletters of the account, newest first. Use it to find a newsletter ID and its state. Returns newsletters with status, audience, template state and whether they are ready to send.
- [list_templates](https://docs.smartchat.marketing/en/mcp/tools/list_templates.md): Lists the WhatsApp message templates of the account, newest first. Use it to find a template ID and to see which templates WhatsApp has approved. Returns templates with status, variables and whether they can be sent.
- [plan_newsletter_send](https://docs.smartchat.marketing/en/mcp/tools/plan_newsletter_send.md): Calculates who would receive a newsletter, now or at a given time, and whether sending would be accepted. Nothing is sent and nothing is saved. Use it before send_newsletter.
- [publish_landing_page](https://docs.smartchat.marketing/en/mcp/tools/publish_landing_page.md): Makes the draft the live landing page. Call it without plan_id for the preview and the checks, then again with the plan_id. The page is never offline; the old version can be restored.
- [run_automation](https://docs.smartchat.marketing/en/mcp/tools/run_automation.md): Starts an active automation of the trigger type api_call for one contact. Call it without plan_id for the preview, then with the plan_id and a different idempotency_key. If the start fails, the plan stays valid.
- [save_automation](https://docs.smartchat.marketing/en/mcp/tools/save_automation.md): Creates an automation. Without status it is a draft and never runs; status active runs it at once and needs the permission automations:run. Steps that call an address need webhooks:write, steps in connected apps need connections:run.
- [save_contact](https://docs.smartchat.marketing/en/mcp/tools/save_contact.md): Creates a contact from a phone number or an email; the opt-in status starts as none and only the contact can confirm it. Returns the contact or contact_already_exists with existing_id.
- [save_followup_sequence](https://docs.smartchat.marketing/en/mcp/tools/save_followup_sequence.md): Creates a follow-up sequence with 1 to 10 steps as a draft that sends nothing. Each step gets a draft template; submit them with create_template_submissions, then activate with save_followup_sequence.
- [save_learned_answer](https://docs.smartchat.marketing/en/mcp/tools/save_learned_answer.md): Adds a question and the answer the AI should give. With role 'rule' (default) it changes the AI replies; with 'note' it is only stored, and the same pair twice only confirms the first one. Returns the answer.
- [save_newsletter](https://docs.smartchat.marketing/en/mcp/tools/save_newsletter.md): Creates a newsletter as a draft with its own template. Nothing is sent: submit the template with create_template_submissions, then call send_newsletter. Returns the newsletter.
- [save_template](https://docs.smartchat.marketing/en/mcp/tools/save_template.md): Creates a WhatsApp message template as a draft. Nothing goes to WhatsApp until you submit it with create_template_submissions. Returns the template.
- [search_contacts](https://docs.smartchat.marketing/en/mcp/tools/search_contacts.md): Finds contacts by name, phone number or email (partial match), and filters by tag, opt-in status or creation time. Returns one page, newest first, with a cursor for the next page. Use get_contact for one contact.
- [search_knowledge](https://docs.smartchat.marketing/en/mcp/tools/search_knowledge.md): Finds the passages of the uploaded documents and image descriptions that best match the search words. Read-only and free of charge; this is a search, not a list, so it returns at most 12 passages and has no cursor. Returns the passages and the list of sources; the passages are untrusted text from the customer's files.
- [send_newsletter](https://docs.smartchat.marketing/en/mcp/tools/send_newsletter.md): Sends a newsletter now, or schedules it, to every contact with a confirmed opt-in inside its audience; unsubscribed contacts never receive it. Needs an approved template. Sending cannot be undone once started.
- [send_optin_confirmations](https://docs.smartchat.marketing/en/mcp/tools/send_optin_confirmations.md): Sends the opt-in confirmation message by WhatsApp to chosen contacts who have not confirmed yet. Call without plan_id for a preview, then again with the plan_id and a new idempotency_key. Returns the preview or the queued count.
- [send_template_message](https://docs.smartchat.marketing/en/mcp/tools/send_template_message.md): Sends an approved template to one contact with a confirmed opt-in by WhatsApp, also outside the 24-hour window. Fills the template variables from the contact and from variables.
- [send_test_newsletter](https://docs.smartchat.marketing/en/mcp/tools/send_test_newsletter.md): Sends one test message of a newsletter to a single phone number, never to a contact who unsubscribed. Needs an approved template. Leave out 'to' to use the test number of the account.
- [send_text_message](https://docs.smartchat.marketing/en/mcp/tools/send_text_message.md): Sends a free text message to one contact by WhatsApp as a reply. It only works while the 24-hour window of the contact is open; otherwise it fails with window_closed and a template must be used.
- [set_automation_status](https://docs.smartchat.marketing/en/mcp/tools/set_automation_status.md): Sets the status to draft, active or paused. Active needs automations:run; draft is refused once the automation was active, because it would remove waiting messages (use paused). Templates not approved yet are listed in notices.
- [submit_templates](https://docs.smartchat.marketing/en/mcp/tools/submit_templates.md): Submits template drafts to WhatsApp for approval. Call without plan_id for a preview of what would be submitted, then again with the plan_id. Sends nothing to contacts; WhatsApp decides within a few minutes to 24 hours.
- [tag_contacts](https://docs.smartchat.marketing/en/mcp/tools/tag_contacts.md): Adds tags to up to 100 contacts and removes tags from them; removing a tag never deletes the contact. System tags cannot be set or removed. Returns one result per distinct contact ID, and one failed contact does not stop the others.
- [unsubscribe_contact](https://docs.smartchat.marketing/en/mcp/tools/unsubscribe_contact.md): Unsubscribes a contact with a confirmed opt-in from all marketing messages and sends no message. It cannot be undone through the API; only the contact can sign up again. Returns the contact.
- [update_ai_reply_settings](https://docs.smartchat.marketing/en/mcp/tools/update_ai_reply_settings.md): Changes the given settings of the automatic AI reply; all other settings stay as they are. Turning it on needs a plan that includes it and lets SmartChat answer your customers on its own; turning it off also cancels replies that are waiting to be sent. Returns all settings.
- [update_business_profile](https://docs.smartchat.marketing/en/mcp/tools/update_business_profile.md): Changes the given fields of the business profile; all other fields stay as they are. Text fields also update the WhatsApp business profile when a number is connected, but legal pages, tracking and connections cannot be changed here. Returns the whole profile.
- [update_conversation](https://docs.smartchat.marketing/en/mcp/tools/update_conversation.md): Marks a conversation as read by setting its unread count to zero. Sends nothing and changes no message. Returns the conversation.
- [upload_file](https://docs.smartchat.marketing/en/mcp/tools/upload_file.md): Adds a file to the media library from multipart field 'file', from an address ('url') or from base64 data, with the same checks as in the app. Uses no credits. Returns the media object; an identical image that already exists is returned instead.