Endpunkte

GET/v1/me

Get the authenticated account and key (test connection)

No scope needed; any valid key works. Use it to test a connection. account.name is a good connection label. key is null when called through OAuth/MCP.

Antworten

GET/v1/contacts

List contacts

Requires scope contacts:read. Non-deleted contacts of the account, newest first (created_at descending, then id). With q: partial match in name, email or phone number, case-insensitive. A phone search may contain spaces and hyphens ("+49 151 123" finds "+49151123...").

Antworten

POST/v1/contacts

Create (or upsert) a contact

Requires scope contacts:write. At least email or phone is required. New contacts start with optin_whatsapp=none / optin_email=none; a double opt-in cannot be triggered through this API. The contact must go through the regular sign-up flow before /messages can reach it.

Upsert (body upsert: true or query upsert=true): if a contact with the same email or phone exists, it is updated (name/email/phone) and 200 is returned with created: false. Changing an email or phone resets the opt-in for that channel to none; the opt-in can never be raised via the API. Without upsert, a duplicate returns 409 contact_exists (key kontakt_email_doppelt, kontakt_nummer_doppelt or kontakt_doppelt, plus contact_id). If the email matches one contact and the phone another, 409 contact_conflict is returned with contact_ids. 403 limit_reached when the plan's contact limit is reached.

Daten (body)

{
  "name": "Max Sample",
  "phone": "+491701234567",
  "acquisition": "marketing"
}

Antworten

GET/v1/contacts/tags

All assigned tags with counts

Requires scope contacts:read. If the same name comes from several origins, the stronger origin wins for display (system > ki > manuell). capped = true means the limit of 1000 checked contacts was reached and the count is incomplete.

Antworten

GET/v1/contacts/{id}

Get a contact

Requires scope contacts:read.

Antworten

PATCH/v1/contacts/{id}

Update a contact

Requires scope contacts:write. Only the given fields are changed.

IMPORTANT: if email or phone changes, the opt-in for EXACTLY THAT channel falls back to none. Consent cannot be moved to another address or number; through this route an opt-in can only fall, never rise.

The contact must still have at least an email or a phone number. A duplicate email or phone returns 409 contact_exists.

Daten (body)

{
  "name": "Maxi Sample",
  "phone": "+491709999999"
}

Antworten

DELETE/v1/contacts/{id}

Permanently delete a contact

Requires scope contacts:delete; contacts:write is NOT enough.

Deletes the same scope as the SmartChat app: pending send jobs, conversations and messages, personal automation runs, then the contact itself. Events and consent records are ANONYMIZED instead of deleted (the statistics stay consistent, and the proof THAT consent existed remains). If the end customer requested deletion, a deletion confirmation is sent to them afterwards (Art. 19 GDPR).

Antworten

POST/v1/contacts/{id}/tags

Add tags

Requires scope contacts:write. Either tag (single) or tags (list). Added tags have the origin manuell (manual).

System tags (e.g. "hat gekauft", "marketing", "herkunft: ...") are rejected with 400: they describe what actually happened and must not be claimed by hand. At most 30 tags per contact.

Daten (body)

{
  "tags": [
    "regular",
    "newsletter"
  ]
}

Antworten

DELETE/v1/contacts/{id}/tags/{tag}

Remove one tag

Requires scope contacts:write. System tags cannot be removed (400); they are a record, not a label.

Antworten

GET/v1/inbox/conversations

List inbox conversations

Requires scope inbox:read. Newest first. automated_only marks conversations that consist only of automated campaign messages (broadcast/follow-up/automation/opt-in), i.e. without a real customer reaction.

There is deliberately NO reply endpoint. To write from an integration, use POST /messages, where the opt-in requirement is visible and checked.

Antworten

GET/v1/inbox/conversations/{id}/messages

Read the history of a conversation

Requires scope inbox:read. Returns the NEWEST limit messages (default 25, max 100), oldest first within the page. offset pages backwards from the newest end. automated marks automated campaign messages, ai a reply written by the SmartChat AI.

Antworten

GET/v1/messages

List messages account-wide (polling trigger "new inbound message")

Requires scope inbox:read. Newest first, stable sort (created_at descending, then id).

Antworten

POST/v1/messages

Send a WhatsApp free-text message or an approved template to a confirmed contact

Requires scope messages:write. The contact must already have optin_whatsapp=confirmed (double opt-in); this route neither creates nor bypasses an opt-in. Send EITHER text OR template, never both.

**Free text (text)** is sent immediately (201). WhatsApp rejects free text outside the 24-hour service window (the send then fails with send_failed).

**Template (template)** works at any time, also outside the 24-hour window. Only the account's own WhatsApp templates with Meta status approved can be sent (GET /templates shows sendable and variables); opt-in confirmation and system templates cannot. Template variables are filled from the contact (name = first name with a language-specific fallback, full_name, email, phone, custom fields) and from template.variables. name, full_name, email, phone and a positional {{1}} used as greeting always come from the contact and cannot be passed. Every other template variable must have a value; unknown variables, empty values, values over 1024 characters, values with line breaks, tabs, control characters or four spaces in a row, and values that contain a placeholder are rejected with 422 invalid_variables (the message names the variables). If the final text would still contain a placeholder, nothing is sent.

A template message is checked immediately (contact, opt-in, opt-out list, template status, variables, account lock, monthly quota, connected number) and then QUEUED (202 with send_id). SmartChat sends it within seconds through exactly the same path as every other message of the app (opt-out and opt-in are checked again right before sending, monthly quota is reserved atomically). Follow the result with GET /sends/{id}. Messages cost no credits; each sent message counts against the monthly message quota like any other message.

Links in the text: http(s) addresses get UTM parameters (utm_source=smartchat, utm_medium=whatsapp, utm_campaign=api) and are sent as a short link <app-host>/public/t/c/<id> so clicks are counted. The short link redirects immediately. Unchanged are SmartChat's own addresses, addresses with their own utm_source, signed addresses (signature, token or expiry parameters also get no UTM) and texts that would become too long.

Daten (body)

{
  "contact_id": "3f2c8a1e-0000-4000-8000-000000000000",
  "text": "...",
  "template": {
    "id": "3f2c8a1e-0000-4000-8000-000000000000"
  }
}

Antworten

GET/v1/sends/{id}

Status of a queued template message

Requires scope messages:write. Only template sends created with POST /messages (template) of this account; everything else is 404.

Antworten

GET/v1/automations

List automations

Requires scope automations:read.

Antworten

POST/v1/automations

Create an automation

Requires scope automations:write.

The same deterministic safety rules apply as in the SmartChat app: an automation with a mailing-list/newsletter intent always gets a double opt-in step prepended, and a follow-up sequence disguised as an automation (several messages >= 24 h apart) is reduced to the first, immediate message. So this route never creates an automation that sends marketing to contacts without consent.

Triggers with a webhook (generic_webhook, purchase) automatically get an address; it is available at GET /webhooks/{id} (scope webhooks:read). Trigger type values are fixed identifiers: datum = date, termin = appointment, inaktivitaet = inactivity.

Daten (body)

{
  "name": "New order",
  "trigger_type": "generic_webhook",
  "actions": [
    {
      "type": "tag",
      "tag": "customer"
    }
  ]
}

Antworten

GET/v1/automations/{id}

Get an automation

Requires scope automations:read. The secret hook token is NOT part of the response; only has_hook says whether there is an address. The address itself is available at GET /webhooks/{id}.

Antworten

PATCH/v1/automations/{id}

Update an automation (including activate/pause)

Requires scope automations:write. status: "active" activates, "paused"/"draft" pauses.

Two behaviors to know: trigger_config is MERGED, not replaced (a partial update does not silently remove the calendar address). And when pausing, already queued pending messages of this automation are stopped; otherwise a delayed action would still go out despite the pause.

Daten (body)

{
  "status": "active"
}

Antworten

DELETE/v1/automations/{id}

Delete an automation

Requires scope automations:delete; automations:write is NOT enough. Pending messages of this automation are stopped first, so nothing goes out in its name after deletion.

Antworten

GET/v1/automations/{id}/runs

Runs of an automation

Requires scope automations:read. Newest first.

Antworten

POST/v1/automations/{id}/trigger

Trigger an automation with a payload

Requires scope automations:write. Runs the same action chain as a regular trigger (webhook/internal event). There is no test mode; results are real (messages are sent, etc.).

Daten (body)

{
  "payload": {}
}

Antworten

GET/v1/webhooks

List incoming webhook addresses of automations

Requires scope webhooks:read.

An incoming webhook is the inbound address of an automation with a webhook trigger. There is no separate resource: CREATE means POST /automations with trigger_type: generic_webhook (or purchase), DELETE means deleting the automation. For outgoing event notifications see /webhook-subscriptions.

Separate scope because the address contains the SECRET hook token: whoever has it can trigger the automation without any API key, even after the key was revoked. Rotating the token is deliberately not offered here.

Antworten

GET/v1/webhooks/{id}

Setup package of an incoming webhook (address, embed code, state)

Requires scope webhooks:read. {id} is the automation id. If the trigger needs no address at all (e.g. keyword, datum), the API answers 400.

connection.state answers the question where most setups fail: waiting_for_first_event (address ready, nothing received yet), running (at least one real event received), not_connected (calendar without address), internal (trigger needs no connection).

Antworten

GET/v1/webhook-subscriptions

List webhook subscriptions

Requires scope webhooks:read.

Antworten

POST/v1/webhook-subscriptions

Subscribe a URL to an event (REST hook)

Requires scope webhooks:write plus the read scope of the event: contact.created needs contacts:read; message.received and conversation.created need inbox:read. Only available with an API key (not via OAuth/MCP).

The URL must use https, be at most 2000 characters and resolve to a public IP address. At most 10 active subscriptions per account (409 webhook_limit_reached). The signing secret (whsec_...) is returned ONLY in this response. See the tag description for delivery details.

Daten (body)

{
  "url": "https://hooks.example.com/smartchat",
  "event": "message.received"
}

Antworten

DELETE/v1/webhook-subscriptions/{id}

Delete a webhook subscription

Requires scope webhooks:write. 404 if not found in this account.

Antworten

GET/v1/templates

List templates

Requires scope templates:read. Each item also has variables (the placeholders of the approved version, in order), settable_variables (the ones that may be passed in POST /messages template.variables; the rest comes from the contact), sendable (can be sent with POST /messages right now) and language.

Antworten

POST/v1/templates

Create a template

Requires scope templates:write. The template is created as a DRAFT; it is only submitted deliberately via POST /templates/{id}/submit (separate scope templates:submit), so an unchecked template never burns a scarce Meta submission slot.

purpose controls the Meta category: optin_confirm and utility are sent as UTILITY, marketing as MARKETING. Opt-in templates ALWAYS get the fixed, language-bound confirm button; a custom button label would break the YES detection in the webhook and thus the double opt-in, and is rejected.

language matters more than it seems: at Meta a template is identified by (name, language). If omitted, the account language applies.

Check messages (issues, rejection_reason_text) are English.

Daten (body)

{
  "name": "Welcome",
  "content": "Hi {{1}}, great to have you here!",
  "purpose": "marketing",
  "language": "en_US"
}

Antworten

GET/v1/templates/{id}

Get a template

Requires scope templates:read. state is the state (draft/pending/approved/rejected/paused/disabled), submittable says whether submitting makes sense right now, issues lists the reasons if not.

Antworten

PATCH/v1/templates/{id}

Update a template

Requires scope templates:write.

ANY content change to a WhatsApp template (text, button, language, name, header image) resets meta_status to null. This is the WABA rule: the changed version must not be sent under the old approval. After a change the template must be submitted again.

Daten (body)

{
  "name": "...",
  "content": "...",
  "subject": "...",
  "language": "...",
  "buttons": [
    {}
  ],
  "header_media": {}
}

Antworten

DELETE/v1/templates/{id}

Delete a template

Requires scope templates:delete. If the template is still attached to a follow-up step or an automation, the API answers 409 instead of letting a later send fail. A template known to Meta is also removed there; if that fails, the reason is in notice - locally it is deleted anyway.

Antworten

POST/v1/templates/{id}/submit

Submit a template to Meta

Requires scope templates:submit; templates:write is NOT enough. Separate scope because something goes OUTSIDE here: Meta strictly caps submissions per WABA, and rejected templates affect the quality rating of the number.

The same deterministic check as in the SmartChat app runs first; if the template fails, it is NOT submitted at all (400 with the reasons). Without a connected WhatsApp number: also 400.

If the template is already at Meta (approved/pending), 200 is returned with already: true and a plain-text notice instead of a false error. If the submission did not reach Meta, the answer is 502 with the reason, never a sugar-coated ok.

Antworten

GET/v1/newsletters

List newsletters

Requires scope newsletters:read.

Antworten

POST/v1/newsletters

Create a newsletter draft (NEVER sent)

Requires scope newsletters:write. ALWAYS creates only a draft (status=draft). There is deliberately NO "send now" in this API; an immediate mass send to all contacts remains a click in the SmartChat app. Scheduling is possible via POST /newsletters/{id}/schedule with the SEPARATE scope newsletters:schedule; the sending itself then runs through the usual safeguards (Meta template approval, opt-in per recipient, credit and subscription gate). WhatsApp only (channel must be omitted or whatsapp).

Daten (body)

{
  "subject": "New this week",
  "content": "Hello! This week we have..."
}

Antworten

GET/v1/newsletters/{id}

Get a newsletter

Requires scope newsletters:read.

Antworten

PATCH/v1/newsletters/{id}

Update a newsletter (button and recipient filter)

Requires scope newsletters:write. At least one of cta or segment must be in the body.

segment filters recipients by tags and is checked against the tags that ACTUALLY exist; otherwise a typo would silently mean "nobody", which would only show after sending. segment: null means "all confirmed contacts" again. cta: null removes the button.

Newsletters that are already sent or currently sending are locked (400).

Daten (body)

{
  "cta": {},
  "segment": {}
}

Antworten

DELETE/v1/newsletters/{id}

Delete a newsletter (draft or scheduled only)

Requires scope newsletters:delete. Sending (sending) and sent (sent) newsletters cannot be deleted; a sent newsletter is the record of what went out to contacts (400). Already queued send jobs are removed first.

Antworten

POST/v1/newsletters/{id}/schedule

Schedule a newsletter

Requires scope newsletters:schedule; newsletters:write is NOT enough. Reason: newsletters:write has always explicitly meant "may create drafts, can never send". If scheduling fell under it, a long-issued key could trigger a real mass send after an update without the customer ever granting that.

This route ONLY sets a time. The sending itself then runs through the usual path and all safeguards: credit gate, opt-in per recipient, Meta template approval, subscription/payment lock.

Allowed is draft -> scheduled and rescheduling. The time must be in the future and at most one year ahead.

Daten (body)

{
  "scheduled_at": "2026-09-10T09:00:00+02:00"
}

Antworten

POST/v1/newsletters/{id}/cancel

Cancel a schedule

Requires scope newsletters:schedule. Only possible while the newsletter is scheduled; it then returns to draft.

Antworten

GET/v1/newsletters/{id}/status

Delivery status of a newsletter

Requires scope newsletters:read. Read-only access to the same counts as in the SmartChat app (send jobs per status); changes nothing.

Antworten

GET/v1/followups

List follow-up sequences

Requires scope followups:read. Changes need followups:write.

CREATING a new step is deliberately not offered: the internal path generates the text with AI and does not bill this call. Through a public interface with 120 requests/minute that would be an unpaid lever on model costs. Text and delay of EXISTING steps can be fully changed.

Antworten

GET/v1/followups/{id}

Get a follow-up sequence

Requires scope followups:read.

Antworten

PATCH/v1/followups/{id}

Activate, pause or rename a sequence

Requires scope followups:write.

status: "active" activates the sequence AND schedules already confirmed contacts for its steps (future times only). Without this, existing contacts would never receive newly activated steps.

Daten (body)

{
  "status": "active"
}

Antworten

PATCH/v1/followups/steps/{id}

Update a follow-up step (text, subject, delay)

Requires scope followups:write. Delay as delay_minutes, delay_hours or delay_days.

Two rules apply: the MINIMUM GAP to the other steps of the same sequence (otherwise a contact would get two messages shortly after each other), and shifting already queued jobs by the difference. verschobene_auftraege (shifted jobs) says how many pending messages were moved. Never into the past: a shortened delay sends from now at the earliest, not retroactively as a burst.

Daten (body)

{
  "content": "A quick reminder about your offer.",
  "delay_days": 3
}

Antworten

GET/v1/settings/profile

Read profile (company name, UI language)

Requires scope settings:read.

Antworten

PATCH/v1/settings/profile

Update profile

Requires scope settings:write. At least one field must be set.

Daten (body)

{
  "name": "...",
  "ui_language": "en"
}

Antworten

GET/v1/settings/brand

Read brand settings (color, tone, logo, test number)

Requires scope settings:read.

Antworten

PATCH/v1/settings/brand

Update brand settings

Requires scope settings:write. A color set here counts as chosen by the customer; a later AI build will not overwrite it. test_phone is the number for newsletter test sends (international format; an empty string removes it).

Daten (body)

{
  "color": "...",
  "tonality": "...",
  "logo_url": "...",
  "test_phone": "..."
}

Antworten

GET/v1/settings/legal

Read imprint/privacy policy URLs

Requires scope settings:read.

Antworten

PATCH/v1/settings/legal

Set imprint/privacy policy URLs

Requires scope settings:write. These are the CUSTOMER's URLs; for the WhatsApp opt-in the customer is the data controller. URLs on SmartChat's own domains are therefore rejected with 400.

Daten (body)

{
  "imprint_url": "...",
  "privacy_url": "..."
}

Antworten

GET/v1/settings/followup-timing

Read follow-up send times

Requires scope settings:read.

Antworten

PATCH/v1/settings/followup-timing

Update follow-up send times

Requires scope settings:write. send_time in the format HH:MM, timezone as an IANA name (e.g. Europe/Berlin). null means "no fixed time"; timing then stays exact to the second from confirmation. Steps of other accounts in steps are silently skipped.

Daten (body)

{
  "send_time": "...",
  "timezone": "...",
  "steps": [
    {}
  ]
}

Antworten

GET/v1/settings/coexistence

Use the WhatsApp Business app at the same time - read state

Requires scope settings:read. available is only true when a WhatsApp number is connected.

Antworten

PATCH/v1/settings/coexistence

Use the WhatsApp Business app at the same time - toggle

Requires scope settings:write. Enabling requires a connected WhatsApp number (otherwise 400).

Daten (body)

{
  "enabled": true
}

Antworten

GET/v1/settings/channels

Read channel state (read only)

Requires scope settings:read. The question an integration should ask before sending: is a number connected, and is sending currently stopped (Meta block, invalid access)? While versand_moeglich (sending possible) is false, NOTHING goes out - no newsletters, follow-ups or automations.

Connecting and disconnecting a WhatsApp number is deliberately not offered: it is a Meta OAuth flow with an access token, and disconnecting removes template bindings including the queue.

Antworten

GET/v1/team

List team members (read only)

Requires scope team:read. No inviting/removing via this API; account and permission changes remain exclusive to the SmartChat app.

Antworten

GET/v1/stats

Statistics summary

Requires scope stats:read. The same aggregation as the statistics page in the SmartChat app.

Antworten

GET/v1/media

List the media library (read only)

Requires scope media:read. No upload via this API: the internal upload logic (file signature check, SVG sanitizing, EXIF removal, WhatsApp compression, duplicate detection) is tied to the internal handler.

Antworten

GET/v1/openapi.json

This API description as JSON

Public, no authentication. /openapi.yaml returns the same document (JSON is valid YAML).

Antworten