tawked.com. Filter by product with the tags, or follow the RSS feed. A change that can break a working integration carries the Breaking tag.
Campaigns v2: saved segments, store offers, results, follow-ups, and campaign webhooks
- Audiences: saved segments (
campaigns.segments.*, counted withcampaigns.segments.countbefore they are saved), ready-made presets, rules on orders and engagement, and exclusions. See Campaigns. - The message: a goal, A/B variants, a comparison group, a coupon (one shared code, or a personal code per customer issued by the store,
campaigns.coupons.show), a limited-time offer, and a follow-up to who read or tapped (campaigns.campaigns.follow_up). - Results:
campaigns.campaigns.results, the funnel with taps and the orders and revenue the campaign brought, andcampaigns.campaigns.retargetfor the next campaign from one of its groups. - Approvals: scheduling binds every v2 field and the saved segments its audience reads; deleting a saved segment, adding a follow-up, and a Shopify or WooCommerce store’s consent or disconnection ask the person first. A new human action,
store_coupon_scope, when the store has not granted Tawked the coupons permission. - The MCP server: two named tools,
get_campaign_resultsandcount_campaign_audience. - Webhooks:
campaign.started,campaign.pausedandcampaign.completed, in a new group,campaigns, ticked by default on a new endpoint of an application that sends WhatsApp; an endpoint made before keeps the events it chose. See Webhook events.
message.sent, message.delivered, message.read, message.failed) of campaign messages, unless the application turns them on: Campaign settings in the console, or campaigns.settings.update with campaign_message_webhooks: true. The statuses of every other message are unchanged.Receive email: addresses, the API, forwarding and the email.received webhook
- Receiving addresses:
<anything>@<name>.inbound.tawked.comat once, or<anything>@inbound.<your domain>with one MX record on a subdomain of a domain you already send from. See Receiving email. - The API:
GET /v1/email/receivedandGET /v1/email/received/{id}(bodies, headers, attachments, verdicts andreply_headersto thread a reply),GET /v1/email/received/{id}/raw,GET /v1/email/received/{id}/attachments/{attachment},DELETE /v1/email/received/{id},POST /v1/email/received/{id}/forwardandGET /v1/email/inbound-addresses. - A new key scope,
email:inbound, off on every key, full access included: switch it on for the keys that read received mail. A forward needsemail:sendtoo. email.received, a new webhook event with the email’s metadata, sent to the endpoints that choose it.- New codes:
409 received_not_ready,410 received_content_gone,413 forward_too_large,422 forward_risky_attachment.
email:inbound, and no existing endpoint receives email.received until you tick it.The developer surface: manage Email by API, test mode, templates, tracking, previews and Standard Webhooks
- Manage by API with a live key that holds the new, explicit
email:manage: domains (/v1/email/domains), the suppression list (/v1/email/suppressions, imports included), metrics (GET /v1/email/metrics), templates and a message’s kept copy (GET /v1/email/messages/{id}/content).webhooks:managemanages the application’s webhook endpoints (/v1/webhooks). A full-access key holds neither: choose them on the key. A sending key can be limited to one domain. - Test mode: a
tk_test_key sends to the simulator addresses (delivered@sim.tawked.comand its siblings), with the whole flow of statuses and webhooks, nothing sent and nothing charged. - Templates:
{{ KEY }}placeholders with fallbacks, a draft and numbered versions, sent by id or alias over the API (template) and SMTP (X-Tawked-Template). - Open and click tracking per domain, on your own subdomain over HTTPS; off by default.
- Previews: an application can keep a copy of each message for its 30 days; off by default.
- Webhooks: new events
email.sent,email.delivery_delayed,email.suppressed,email.scheduled,email.canceled,email.opened,email.clicked,domain.*andsuppression.*; Standard Webhooks signing beside the Tawked signature; replays; Email endpoints retried over about 27.6 hours and switched off after five days of failures.
to and recipient.address carry the full address, the bodies gain type and timestamp, retries last longer, and an endpoint failing for five days is switched off with a notice. No new event or header reaches an existing endpoint until its owner adds it, and email.failed with recipient_suppressed keeps coming.Send like Resend: recipients, batches, scheduling, headers and tags, for less
- Up to 50 recipients a message:
totakes one address or an array, andccandbccare honoured, each with a display name (Sara Ali <sara@example.com>), duplicates sent once, a suppressed address skipped rather than refusing the message.reply_totakes up to 10 addresses, andfroma string. See Recipients. headersandtagsare honoured: your own headers, one-click unsubscribe among them (422 header_not_allowedfor the ones Tawked sets), and up to 20 tags returned on the message and its webhooks. See Custom headers and Tags.POST /v1/email/messages/batch: up to 100 messages in one call, all or nothing by default (422 batch_invalid), orTawked-Batch-Validation: permissive.- Scheduling:
scheduled_atup to 30 days ahead,PATCH /v1/email/messages/{id}to move it andPOST /v1/email/messages/{id}/cancelto cancel it, refunded (409 message_not_scheduledonce it is on its way). GET /v1/email/messageslists the application’s messages, filtered by status, recipient, reference, tag and date, a page at a time.- The price: 3,000 emails free every month, then 100 halalas per 1,000, every recipient one e-mail. The free e-mails start after the account’s first paid top-up (a signup bonus or a team credit is not one).
price_halalasis the whole halalas a message took from the balance: 0, or 1 about every tenth e-mail. - Limits: 5,000 e-mails a day per account by default, counted per recipient on the day it is sent, and 10 requests a second (
429 rate_limitedwithRetry-After: 1); a send answersRateLimit-Limit,RateLimit-Remaining,RateLimit-ResetandTawked-Daily-Remaining. The per-key limit on the e-mail endpoints is 1,200 a minute, and429 too_many_requestsnow carriesRetry-Afteron every endpoint.503 email_platform_busyanswers, rarely, when Tawked’s whole sending day is used. - Webhooks: one
email.*event per recipient,dataaddingrecipientandtagsfor a message of several; every webhook delivery, of every product, carries atawked-webhook-idheader to dedupe on. See Duplicates and order. - Retention: messages are kept for 30 days, then deleted; daily figures and the suppression list stay. A message’s body is kept encrypted only until it is sent.
- Deliverability: a send that links to a host on Tawked’s list of blocked hosts answers
422 content_blockedwithhost(SMTP554 5.7.1), and a rare hold on all of Tawked Email answers503 service_unavailable(SMTP451 4.3.0); nothing is recorded or charged. A pause after the202no longer fails the message at once: it staysqueuedand charged, is sent if the pause lifts within 12 hours of its time, and otherwise fails withqueue_expired, refunded once. A domain can send from its own return path (send.<your domain>, SPF aligned), and its page reads its DMARC record. See Sender domains and Suppressed addresses. - SMTP: an e-mail is one message with all its recipients (To and Cc kept, Bcc hidden), your headers passed on,
X-Tawked-Tags,X-Tawked-Referenceand three idempotency headers read, and a clear535at sign-in for an account not yet granted Email. See Sending over SMTP.
to string, no cc, bcc, tags or scheduled_at) answers exactly as before. cc, bcc, headers and tags were ignored and are now honoured, so a request that already sent a valid cc, bcc or tags now answers the extended shape (to an array, with recipients and cost) and its webhooks carry recipient; an invalid value sent with a key made before 2026-10-21 is dropped, not refused, until 2026-11-25. A message is now queued: a failure at the sending service arrives as its failed status and an email.failed webhook (new error.code values: email_paused, email_early_access, sender_not_verified, recipient_suppressed, queue_expired) instead of a 502 send_failed or a 503 for a pause at the sending service; 503 email_paused still answers at once when the application’s own sending is paused. GET right after the 202 reads accepted. An SMTP e-mail to several recipients is now one message id, with one webhook per recipient, where each recipient was its own message before.A placeholder’s name is at most 20 characters
Meta approves a template whose named placeholder is longer than 20 characters, such as{{subscription_start_date}}, then refuses every message sent from it with its error 100. Tawked now stops it earlier. See Placeholder names.POST /v1/whatsapp/templatesandPATCH /v1/whatsapp/templates/{template_id}refuse such a name with400 invalid_requestand the reasonplaceholderName, as the console and the MCP server do.POST /v1/whatsapp/messagesfrom a template that already has one answers422 unsupported_templatewithmessagelong_placeholder_name. Nothing is sent or charged, where Meta’s refusal came back as a failed message before.
Meta’s charges on the Account API, and Verify’s business document
whatsapp.charges.show(GET /v1/applications/{application}/whatsapp/charges, permissionwhatsapp:read): what Meta charged on the application’s WhatsApp number this month and last, by Meta’s category, with anestimatewhere Meta keeps the amount from Tawked (the number’s WhatsApp account is the business’s own), the number’s free replies this month, and Tawked’s own fee per template message. The console’s charges card and free replies meter, read by an agent.account.document.update(PUT /v1/account/document, the owner’s alone): saves the account’s business document, a commercial registration or a freelance certificate with its number.- Verify now needs that document as well as the confirmed business e-mail:
applications.products.addandapplications.applications.createanswer409 business_document_missingforverifyon an account without one, and the answer’snextnamesaccount.document.update. An account that signed up through Verify’s own door already has it.
The Account API, and one MCP server for your agent
Everything a person does in the console is now an operation an agent or a script can call, at the same base URL with a new credential: an account token (tk_acct_), made under Settings → Account API. A token acts as the person who made it, never beyond their role, narrowed by permissions per area (read, or read and write, or *), optionally to some applications and to some IP addresses, with an optional expiry. Start with GET /v1/me (its next_steps say what is left to set up), find operations with GET /v1/operations?q=…, read one’s input with GET /v1/operations/{id}. Every operation is in the new Account API tab. See Account API, and the quickstart for Claude Code, Claude, ChatGPT, Cursor, Codex and a script.- When a person must act, the answer carries
human_action: a stablereason, theurlthe person opens, the sentence tosayto them, and the operation to callthen. See The person in the loop. - Every answer says what to do next:
nextnames the operation to call and how often to read again, following the state of what it answers, and every refusal carries one. An unknown operation or address answersdid_you_mean, andGET /v1/operations/{id}says what each path parameter is and which operation lists its values; a body that is not JSON400 invalid_json; a revoked or expired token401 token_revokedor401 token_expiredwith the link to make a new one. - Approvals: a token made with Ask me first (the default) answers a consequential call (it reaches customers, spends money, deletes, or cannot be undone) with HTTP
428 approval_required; a2xxalways means the operation ran. The person approves the exact request in the console, its key facts named (the application, the template, the masked recipient and the sending number, the person added, the campaign and its recipients), and the same request sent again withTawked-Approval(and the sameIdempotency-Key, if any) runs once. A call that could not run anyway (a body with fields to fix, then the operation’s own checks) is refused first, and nobody is asked to approve it. - Security: every call on record for 90 days (
account.tokens.activity), an e-mail when a token is made, an address allowlist (403 ip_not_allowed), andTawked-Untrusted-Content: trueon answers holding text written outside the account. See Security. - The Tawked MCP server at
https://tawked.com/mcphas one model: every connection holds an account token, made by the assistant’s sign-in (everything you can do, or read only, on the applications you choose) or typed into its settings, such as Claude Code’s--header "Authorization: Bearer tk_acct_…". Four tools reach every operation:search_tawked_api,describe_tawked_operation,read_tawked_apiandcall_tawked_api; the named tools for templates, messages and Verify test codes run their operations too, and are listed by the token’s permissions.call_tawked_apiis always listed on/mcp, so a permission allowed mid-conversation works at once. - Assistants that signed in before keep only reads: their old keys became one account token with the reads of the areas they reached (Verify, WhatsApp). To let one write again, allow more on its token’s page under Settings → Account API, or sign it in again with Everything you can do.
- Keys typed into an assistant keep working until 15 November 2026: replace them with a sign-in or an account token.
- Application keys and the sending API are unchanged.
A connected app sets up its customer’s auto-attendant
A connected app can now build the auto-attendant of its connection’s application, the menu of tappable choices that answers a new conversation on its WhatsApp number in Tawked Chat, publish it and switch it on, so the customer does nothing. See Set up the auto-attendant for your client.- Five calls in the Chat group of the API reference:
GET /v1/chat/attendant,PUT /v1/chat/attendant/draft,POST /v1/chat/attendant/publish,PUT /v1/chat/attendant/stateandPATCH /v1/chat/attendant/settings. The console and the API share one draft, and the last save wins. - A new scope,
chat:attendant, a connected app’s alone: the customer approves it on the consent page with the app’s other permissions, and Tawked’s team extends it to the existing connections of an app the customer already approved. A business’s own key, full access included, answers these calls403 insufficient_scope. - New error codes:
attendant_no_draft(409),attendant_unpublished(409),sending_blocked(409, withreasonpaymentorblocked) andattendant_not_ready(422, with the draft’sproblems). - When a connection ends, the auto-attendant stays as it is: it is the customer’s.
A connected app adds conversation menus to its customer’s Tawked Chat
A connected app can now add a conversation menu, a tab beside the conversations of its connection’s application, so the customer does nothing. See Add a conversation menu for your client.- Five calls in a new Chat group of the API reference:
GET /v1/chat/menus,POST /v1/chat/menus,GET /v1/chat/menus/{id},PATCH /v1/chat/menus/{id}andDELETE /v1/chat/menus/{id}. An app reads and changes only the menus its connection made. - A new scope,
chat:menus, a connected app’s alone: the customer approves it on the consent page with the app’s other permissions, and Tawked’s team extends it to the existing connections of an app the customer already approved. A business’s own key, full access included, answers these calls403 insufficient_scope. - New error codes:
chat_not_ready(409, withreasonchatornumber),menu_limit_reached(422) andchat_unavailable(503). - When a connection ends, the menus it made are removed from Tawked Chat. The customer sees the app’s menus in the console’s list, with the app’s name, and may edit or delete them.
Templates that open with a PDF attachment
A WhatsApp template can now open with a document, a PDF such as an invoice, a contract or an attendance sheet, and each message carries its own file. See Send a PDF attachment.POST /v1/whatsapp/messagestakesheader.document:{ "link": "https://...", "filename": "Contract-1042.pdf" }.linkis required for such a template, an https link to the PDF that Meta downloads when it sends;filenameis the name the customer sees. A missing or refused link answers422 invalid_params, aheaderof another shape400 invalid_request.unsupported_templateno longer covers document headers; video and location headers still answer it.- For a connected app’s key,
POST /v1/whatsapp/templatesandPATCH /v1/whatsapp/templates/{template_id}takeheader_format(TEXT,IMAGEorDOCUMENT) andheader_sample_url, the sample Meta reviews the template with. A refused sample answers400 invalid_requestwithheaderSampleMissing,headerSampleUnreachable,headerSampleInvalidorheaderSampleTooLarge. - A template that opens with an image or a document is now edited over the API like a text one, with
header_formatin the body. Without it, the edit still answers409 template_not_editablewithstatusMEDIA_HEADER, as does any edit of a template that opens with a video or a location. - Templates made on Notifications → Templates can open with a document too.
Tawked Email: transactional e-mail from your own domain, in early access
A fourth product, in early access: apply from the application’s Email area in the console, and once Tawked’s team approves the account, verify a domain with one TXT record on Email → Setup (Tawked makes the domain’s DKIM key and the record publishes its public half), then send one message per call withPOST /v1/email/messages and read it with GET /v1/email/messages/{id}, with a live key and the new email:send and email:read scopes. Until the approval a send answers 403 email_early_access. Bounces and complaints suppress the address for the account, and four new events reach the application’s webhook: email.delivered, email.bounced, email.complained and email.failed. Priced per message from the same balance, nothing monthly. See Tawked Email.A key with full access covers Email already; a custom key needs Email added, on a new key.Make your connected app in the console
A platform no longer writes to Tawked to have its app registered. A partner account makes its app in the console, under Integration apps: its names, its logo, its website and its return addresses, with the client id and the client secret on the app’s own page.- Until Tawked approves it, an app is in test mode: it connects to the applications of the account that made it, and to no other account’s.
- The app is sent for review from its page. Tawked approves it or sends it back with the reason, and once approved any Tawked customer can connect it.
- A change to an approved app’s name, logo, website, return addresses or Connect page waits for Tawked’s review, and the current ones keep working meanwhile.
Connected apps: a Connect button for platforms
A platform that serves many businesses can now work on its customers’ Tawked applications without a pasted key. The customer presses Connect, signs in to Tawked, chooses one application and allows the app; the platform’s server receives a credential for that one application, and the customer disconnects it from Tawked at any time. See Connected apps.- Four template operations on the API:
GET /v1/whatsapp/templates/{template_id}reads one template in full, for any live key withnotifications:read;POST /v1/whatsapp/templates, andPATCHandDELETE /v1/whatsapp/templates/{template_id}, create, edit and delete a text template, for a connected app’s key alone. A key you create, full access included, answers those three403 insufficient_scope. GET /v1/whatsapp/templatesaddsidandmanagedto each row.- New error codes on the template writes:
template_not_managed,template_in_use,template_not_editableandtemplate_refused.
Conversation menus in Tawked Chat
A business can show its own web page beside every conversation in Tawked Chat, on the web and in the phone app, from Chat → Conversation menus in the console. The link can carry the open customer through tokens such as{customer_phone}, and a page that loads https://tawked.com/js/tawked-chat-menu.js receives the open conversation with TawkedChat.onConversation. See Conversation menus.A logo no longer sends a live application back to review
The logo never reaches a message, so Tawked no longer reviews it. Uploading or removing a logo on an active application keeps it active, and its codes keep sending. This holds for the console and forPOST and DELETE .../logo on the Partner API, which no longer fire service.review_requested for a live application.A rejected application is the one exception: a new logo, or its removal, returns it to review, since the rejection may have been about the logo. Names and the website are reviewed as before.Breaking: a partner’s client applications are Verify only
A client application a partner provisions is now Tawked Verify only, and it stays the partner’s. Everything about Verify on the Partner API answers byte for byte as before. Removed:- The owner hand-over:
GET,POSTandDELETE /v1/partner/applications/{external_id}/owner, and theservice.owner_invited,service.owner_acceptedandservice.owner_revokedevents. - WhatsApp on client applications:
GET .../{external_id}/whatsapp, the templates under.../whatsapp/templates(list, read, create, update, delete) and the team under.../whatsapp/team(list, add, remove). GET /v1/partner/messages, and themessage.*events on the partner webhook.- The
ownerandwhatsappblocks of an application row, andprices.whatsapp_message_halalasandowner_invite_capsof the profile.
Reasons on rejections
service.rejected carries a reason_code when Tawked rejects an application, from a fixed list, with whether the rejection may be appealed. See Partner events.Key access by product
A key has full access, or custom access per product:verify:check, verify:send, notifications:read, notifications:send. A call outside the key’s access answers 403 insufficient_scope, with a WWW-Authenticate header that names the scope it needs. Existing keys keep exactly what they could do. See Key access.Image headers on WhatsApp templates
A template that opens with an image now sends: pass the image’s public link inheader.image.link. Such a template sent without it answers 422 invalid_params, where it answered 422 unsupported_template before. See Sending messages.Marketing opt-outs
A MARKETING template to a recipient who asked the application to stop its marketing answers422 consent_opted_out. Nothing is sent or charged. Utility and authentication templates still reach them.Webhook test events and sending again
Send a test event on an application’s Webhooks page delivers a signed sample whose envelope carries"test": true. A failed delivery can be sent again from the Delivery log, so handlers should be idempotent on data.id and the event name. See Webhooks.Three template categories and authentication templates
Templates come in Meta’s three categories: utility, marketing and authentication. An authentication template sends a one-time code from your own WhatsApp number with one value,"params": { "code": "482913" }, of 4 to 15 letters or digits. Tawked stores the code masked. See Templates and Sending messages.Tawked is now three products on one balance: Tawked Verify, Tawked Notifications and Tawked Chat. Nothing changed under /v1.The Partner API grows
A partner sandbox key,tk_partner_test_; an Idempotency-Key on every write; bulk provisioning; archiving and restoring; a verification log; and an event feed with webhooks you subscribe to by event. See Partner API.The message log, the WhatsApp templates and the team over the Partner API, also announced in this release, were removed on 2026-10-04.
The verification lifecycle, idempotency, protection and webhooks
GET /v1/verify/{id},POST /v1/verify/{id}/resendandPOST /v1/verify/{id}/cancelcomplete the lifecycle.startaccepts anIdempotency-Keyheader, areferenceand autofill-ready messages.- Per-application spend caps and per-IP limits guard against SMS pumping.
- Keys can carry an expiry and an IP allowlist, and a check-only key could be created. Check-only keys became the custom access of 2026-10-04.
- Each application can receive signed webhooks for verified, failed and expired verifications.
The sandbox
tk_test_ keys call the same endpoints with the same shapes before the application is approved. Codes are real, stamped [TEST], and reach the account owner’s phone only. Today you create the test key yourself, under Application settings → API keys. See Testing and the sandbox.Verify settings per application, and the partner platform
Code length from 4 to 8 digits, a lifetime from 1 to 15 minutes, 1 to 5 attempts and an hourly cap per number, set in the console only, so a leaked key cannot weaken them.Platforms got one account that creates an application per merchant withPOST /v1/partner/services.