The TikTok DM outreach API

Is there an official TikTok API for sending DMs?

No. As of June 2026, TikTok offers no official API for initiating direct messages to people who haven't contacted you first. The only official messaging surface — the Business Messaging API — is built for inbound support, not outreach.

Its constraints make that explicit: a user must message your business first, you get a 48-hour reply window, you can send roughly 10 automated messages per window, and broadcasting is disallowed. That's exactly why inbound tools built on it (ManyChat being the best-known) cannot initiate a single cold DM.

So every true cold-DM tool on the market operates outside the official API — including Hooka. We say that plainly because it shapes the whole design: the Hooka API is a managed programmatic layer over real TikTok accounts. You call clean REST endpoints; Hooka runs real browsers with each account's session, connected through a dedicated residential IP in your accounts' country, enforces message spacing and per-account daily caps server-side, and when TikTok shows a "sending too fast" warning it puts the message back in the queue and pauses that account for 5 minutes. The numbers behind those defaults are in our guide to TikTok DM limits in 2026.

What do you need before the first call?

1. An active (or trialing) subscription. Your plan sets how many TikTok accounts you can connect (seats). Without one, POST /v1/senders returns 403 no_active_subscription and the engine sends nothing, even if a campaign shows as running and the API returns no error.
2. Each account's country. Every account you connect gets its own dedicated residential IP in its country, so TikTok doesn't see a login from a data centre. Pass country (ISO 3166-1 alpha-2) when you create the sender, or let it use your workspace's default country. It can't be changed later.
3. An hk_live_ API key. Create it on the Developers page of your dashboard. It is stored only as a sha256 hash and shown exactly once, so copy it when you create it.

One call tells you whether you're ready: seats.used must be below seats.limit, and exit_ip.region is the default country new senders get when you don't pass country.

export HOOKA_API_KEY="hk_live_..."   # your key, from the Developers page

curl https://api.hooka.to/v1/workspace \
  -H "Authorization: Bearer $HOOKA_API_KEY"

# → 200
{
  "id": "ws_3f1c2a9e-7b4d-4c1e-9a0b-5d6e7f8a9b0c",
  "object": "workspace",
  "name": "Default",
  "created": 1788000000,
  "exit_ip": { "status": "ready", "region": "ES", "suggested_region": null, "per_sender": true },
  "seats": { "limit": 3, "used": 1 }
}

"no_region" only means there is no confirmed default country: it doesn't block, pass country when you create the sender. If something is missing, POST /v1/senders answers 400 country_required, 403 no_active_subscription or 403 sender_limit_reached, and 409 exit_ip_not_ready (with retry_after) if there's no IP available right now in that country or its nearest ones.

How does the Hooka API work?

It works the way you'd expect if you've used Stripe: REST over HTTPS, JSON, bearer keys, typed object IDs, cursor pagination and idempotency. The conventions:

• Base URL: every endpoint lives under https://api.hooka.to/v1. It is meant for server-to-server calls: don't put your key in code that runs in the browser.
• Keys: send Authorization: Bearer hk_live_.... hk_test_ keys exist (POST /v1/api_keys with {"mode": "test"}) but are read-only: any POST, PATCH or DELETE returns 403 test_key_read_only. There is no sandbox: every write acts on your real TikTok accounts.
• JSON only: send every body with Content-Type: application/json, or you get 415 unsupported_content_type (watch out: curl -d without that header sends a form). Bodies are limited to 1 MB.
• Typed IDs: every ID tells you what it points at — snd_ senders (TikTok accounts), cmp_ campaigns, tgt_ targets, con_ conversations, msg_ messages, rpl_ queued replies (returned by POST /v1/conversations/{id}/messages; no endpoint fetches them), sup_ suppressions, we_ webhook endpoints, evt_ events, key_ API keys and ws_ your workspace.
• Timestamps are integer Unix seconds, UTC (created, sent_at…).
• Pagination: lists return {"object": "list", "data": [...], "has_more": true, "next_cursor": "cmp_..."}. Pass limit (1–100, default 50) and, while has_more is true, fetch the next page with starting_after=<next_cursor>. Two exceptions: on GET /v1/events?after=... you continue with after=<next_cursor>, never starting_after (next to after it is a 400, and on its own it returns the events before the cursor, newest first); and GET /v1/webhook_endpoints and GET /v1/api_keys are not paginated: they return every item as {"object": "list", "data": [...]}, with no has_more or next_cursor, and ignore limit.
• Idempotency: every POST except POST /v1/api_keys accepts an Idempotency-Key header (1–255 characters). Keys are kept for 24 hours per workspace. Retrying with the same key and the same request replays the stored response with Idempotent-Replayed: true instead of acting twice. The same key with a different request gives 409 idempotency_key_reuse; while the original is still running you get 409 idempotency_key_in_use — retry shortly with the same key. 5xx, 429 and errors that depend on the state of the moment (such as no_sender_available) are not stored, so a retry with the same key runs again. A replay is a snapshot of the original response, not the current state.
• Rate limit: 300 requests per minute per workspace, shared by all your keys and OAuth tokens. Responses carry x-ratelimit-limit, x-ratelimit-remaining and x-ratelimit-reset; over the limit you get 429 rate_limited with a Retry-After header and retry_after in the body.
• Tracing: every response carries a Hooka-Request-Id header, repeated as error.request_id in errors. Quote it in support tickets.

Errors

Every error uses one envelope. code is the stable value to branch on, and param names the offending field when there is one:

{
  "error": {
    "type": "invalid_request_error",
    "code": "invalid_request",
    "message": "Number must be greater than or equal to 30",
    "param": "settings.rate_limit_seconds",
    "request_id": "req_9eab538a53ad4f74840f1ee1927578d3"
  }
}

type almost always sets the HTTP status: invalid_request_error 400, authentication_error 401, permission_error 403, not_found_error 404, conflict_error 409, rate_limit_error 429 and api_error 500. The two exceptions: invalid_request_error also comes with 413 (body_too_large) and 415 (unsupported_content_type), and api_error can be any 5xx. A resource from another workspace behaves exactly like one that doesn't exist (404).

Most endpoints silently ignore body fields they don't know, so check your spelling: a made-up setting such as spacing_seconds is simply dropped (the spacing between DMs is settings.rate_limit_seconds). The exception is PATCH /v1/senders/{id}, which accepts only label and rejects any other field with a 400 whose param names that field. A PATCH /v1/webhook_endpoints/{id} with none of url, enabled_events or status is also a 400.

Campaigns you create through the API and the ones you create in the dashboard use the same sending engine and show up in both places: the whole feature set, from sender rotation to the unified inbox, works on the same data as your calls.

Quickstart: from API key to a running campaign

This is the entire core flow in four steps: connect a sender, create a campaign, add targets, start it — then listen for events. The examples use the HOOKA_API_KEY variable from the previous section; replace the IDs with the ones your API returns.

1. Connect a TikTok account (sender)

A sender is one of your TikTok accounts. Connection is QR-only: Hooka never asks for your TikTok password. POST /v1/senders creates the sender, with its own dedicated residential IP in the account's country, and opens a connection attempt, but the QR is not in the response: a browser produces it once the IP is ready, usually within seconds (exit_ip.status is provisioning meanwhile, a few minutes at most when a new IP has to be bought).

curl -X POST https://api.hooka.to/v1/senders \
  -H "Authorization: Bearer $HOOKA_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: connect-sales-es-1" \
  -d '{ "label": "Sales ES #1", "country": "ES" }'

# → 201
{
  "id": "snd_5f0c2a8e-7c1b-4b8e-9d3a-2f6a1c9e4b10",
  "object": "sender",
  "platform": "tiktok",
  "username": null,
  "label": "Sales ES #1",
  "country": "ES",
  "status": "awaiting_scan",
  "status_reason": null,
  "health": null,
  "daily_limit": 30,
  "sent_today": 0,
  "connection": {
    "status": "pending",
    "qr_code": null,
    "verification": null,
    "websocket_url": "wss://api.hooka.to/ws/sessions/0b6f7d7e-3f7e-4a0e-8a51-1f2e3d4c5b6a",
    "error": null
  },
  "exit_ip": { "status": "provisioning", "country": null, "fallback": false, "dedicated": true },
  "created": 1790760000
}

Poll the sender every 3–5 seconds and act on connection.status. The sender.connection.qr_generated webhook tells you when the first QR is ready (and carries it), but it is a signal to start polling, not a replacement: the QR can also change without any event, so keep polling while you show it.

export SENDER_ID="snd_5f0c2a8e-7c1b-4b8e-9d3a-2f6a1c9e4b10"

curl https://api.hooka.to/v1/senders/$SENDER_ID \
  -H "Authorization: Bearer $HOOKA_API_KEY"

• pending — the account's IP is being prepared, the browser is starting, or TikTok is loading a fresh QR. Wait, and don't scan an old QR.
• requires_scan — connection.qr_code holds a PNG as a data URI (data:image/png;base64,...). Show it and scan it from the TikTok app, logged into the account you want to connect. Always show the latest QR: if nobody scans it for about 2 minutes, it is replaced.
• scanned — TikTok detected the scan; the user confirms the login on the phone.
• verification_required — TikTok asked "Verify it's you". connection.verification.step says what it wants: choose_method (pick an email or phone from verification.options) or enter_code (send the code the user received) — answer both with …/connection/verify, below. Two more steps take no action (the endpoint rejects them): finishing — TikTok is completing the login, usually because the code was accepted; keep polling — and unsupported — TikTok asked for something Hooka can't handle, such as a captcha or a password. Unless TikTok moves on to a supported step, that attempt ends with verification_unsupported; you can start a new one right away with …/connection/refresh.
• Done when the sender's status is "connected": username is filled in, connection becomes null and the sender.connected webhook fires. If connection.status turns "expired" or "failed", or status turns "disconnected", the attempt is over.

curl -X POST https://api.hooka.to/v1/senders/$SENDER_ID/connection/verify \
  -H "Authorization: Bearer $HOOKA_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: verify-sales-es-1-code-1" \
  -d '{ "action": "submit_code", "code": "123456" }'

# Other actions:
#   { "action": "choose_method", "option_id": 0 }   (an id from verification.options)
#   { "action": "resend_code" }                      (when verification.resend_available is true)

The verify call answers 202 as soon as the action is queued, before TikTok applies it, so keep polling for the result. Use a new Idempotency-Key for each code. A wrong code keeps the step at enter_code with TikTok's error in verification.messages. When an attempt fails, the reason is in connection.error while the sender is still awaiting_scan (status_reason is null), and in status_reason once it is disconnected. POST /v1/senders/{id}/connection/refresh opens a new attempt.

Connect accounts one at a time: every POST /v1/senders or …/connection/refresh cancels any other attempt in progress in the workspace, which ends with status_reason: "superseded". An attempt lasts about 5 minutes from the first QR, longer if TikTok asks for verification.

2. Create a campaign

A new campaign is always draft: nothing is sent until you start it. The main fields:

• message: a string, or {"variants": [...]} with up to 20 variants of 1 to 2,000 characters; one is picked at random for each recipient and step.
• follow_ups: up to 10 steps of {"wait_days": 1–60, "variants": [...]}. wait_days counts from the previous step's send. A follow-up only goes out if the person hasn't replied, and always from the account that sent the previous step.
• Variables: {{first_name}} or any key you put in the targets' variables; {{username}} (alias {{handle}}) is the recipient and {{my_handle}} the sending account. With on_missing_variable: "skip", a target missing a variable is skipped; with "blank" (the default), it is sent with the gap empty.
• settings.sender_ids (1–10 snd_ IDs): the accounts to send from. Leave it out and the campaign takes up to 10 of your oldest connected accounts at that moment. The API can't change the set afterwards (the dashboard can).
• settings.rate_limit_seconds (30–3,600, default 60): the minimum gap between two DMs from the same account.
• settings.daily_limit (1–500, or null): a daily cap for the campaign, all its accounts combined. Each account's own cap still applies.
• settings.dedupe_across_campaigns (default true): skips anyone another of your campaigns has already sent a DM to.

curl -X POST https://api.hooka.to/v1/campaigns \
  -H "Authorization: Bearer $HOOKA_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: ugc-october-create" \
  -d '{
    "name": "UGC outreach - October",
    "client_reference": "crm-4412",
    "message": {
      "variants": [
        "Hey {{first_name}}, loved your last video. Open to a paid UGC collab?",
        "Hi {{first_name}}, we pay creators like you for UGC videos. Interested?"
      ]
    },
    "follow_ups": [
      { "wait_days": 3, "variants": ["{{first_name}}, just bumping this in case it got buried."] }
    ],
    "settings": {
      "sender_ids": ["snd_5f0c2a8e-7c1b-4b8e-9d3a-2f6a1c9e4b10"],
      "rate_limit_seconds": 90,
      "daily_limit": 40,
      "on_missing_variable": "skip"
    }
  }'

# → 201 (the campaign, plus the result for any targets sent inline — none here)
{
  "id": "cmp_4f0c2d9e-1b7a-4c1e-9a53-2e8d7c6b5a41",
  "object": "campaign",
  "platform": "tiktok",
  "name": "UGC outreach - October",
  "client_reference": "crm-4412",
  "status": "draft",
  "message": {
    "variants": [
      "Hey {{first_name}}, loved your last video. Open to a paid UGC collab?",
      "Hi {{first_name}}, we pay creators like you for UGC videos. Interested?"
    ]
  },
  "follow_ups": [
    { "wait_days": 3, "variants": ["{{first_name}}, just bumping this in case it got buried."] }
  ],
  "settings": {
    "rate_limit_seconds": 90,
    "daily_limit": 40,
    "daily_limit_per_sender": 40,
    "dedupe_across_campaigns": true,
    "on_missing_variable": "skip",
    "sender_ids": ["snd_5f0c2a8e-7c1b-4b8e-9d3a-2f6a1c9e4b10"]
  },
  "created": 1790762400,
  "targets_accepted": 0,
  "target_ids": [],
  "targets_skipped": []
}

daily_limit_per_sender is a deprecated alias of daily_limit: despite the name, it is the campaign's cap, not each account's. Use daily_limit. Save the ID:

export CAMPAIGN_ID="cmp_4f0c2d9e-1b7a-4c1e-9a53-2e8d7c6b5a41"

3. Add targets

Up to 1,000 per request (you can also pass the same list as targets when creating the campaign). Each item is a username string or {"username": ..., "variables": {...}}; variable values can be strings, numbers or booleans and are stored as strings.

curl -X POST https://api.hooka.to/v1/campaigns/$CAMPAIGN_ID/targets \
  -H "Authorization: Bearer $HOOKA_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: ugc-october-batch-1" \
  -d '{
    "targets": [
      { "username": "creator.one", "variables": { "first_name": "Mia" } },
      { "username": "creator_two", "variables": { "first_name": "Leo", "followers": 12000 } },
      { "username": "@Creator.One", "variables": { "first_name": "Mia" } },
      { "username": "bad handle!", "variables": { "first_name": "Ana" } }
    ]
  }'

# → 202
{
  "accepted": 2,
  "target_ids": [
    "tgt_9a1b2c3d-4e5f-4a6b-8c7d-9e0f1a2b3c4d",
    "tgt_2e3f4a5b-6c7d-4e8f-9a0b-1c2d3e4f5a6b"
  ],
  "skipped": [
    { "username": "@Creator.One", "reason": "duplicate_in_campaign" },
    { "username": "bad handle!", "reason": "invalid" }
  ],
  "campaign_status": "draft",
  "resumed": false
}

Usernames are normalized (trimmed, leading @ removed, lowercased), which is why @Creator.One counts as a duplicate of creator.one. A valid username has 1 to 40 characters: ASCII letters, digits, _, . and -. Skipped items never become targets and fire no event. The reasons: invalid (not a valid TikTok username), duplicate_in_campaign (already in this campaign, in any status), suppressed (on your Do-Not-Contact list) and duplicate_across_campaigns (another of your campaigns already sent this person a DM, when the campaign deduplicates).

What happens next depends on the campaign's status. In a running campaign, new targets can go out within seconds: they are real DMs. In draft or paused they wait, because adding targets never starts or resumes a campaign. Adding targets to a completed campaign reopens it when one of its senders is connected ("resumed": true, with a new campaign.started). If none is connected, the campaign stays completed with the new targets pending, and the response adds "resume_blocked_reason": "no_connected_sender" (a field that only appears in this case): reconnect a sender, then call POST …/start or POST …/resume.

4. Start it

curl -X POST https://api.hooka.to/v1/campaigns/$CAMPAIGN_ID/start \
  -H "Authorization: Bearer $HOOKA_API_KEY" \
  -H "Idempotency-Key: ugc-october-start"

# → 200: the full campaign, now running, with live stats (excerpt)
"status": "running",
"stats": { "total": 2, "queued": 2, "pending": 2, "processing": 0, "sent": 0, "replied": 0, "failed": 0, "skipped": 0, "reply_rate": 0 }

No body is needed. start needs at least one of the campaign's senders connected (otherwise 400 no_sender_available) and works from draft, paused, or completed with pending targets (otherwise 409 invalid_campaign_state). POST …/pause (from running) and POST …/resume (from paused, or from completed with pending targets) are called the same way. These are real DMs. From here the engine takes over:

• Order: targets go out in the order you added them, with due follow-ups first. Each connected sender of the campaign takes one target at a time, so sends spread across up to 10 senders.
• Spacing: at least rate_limit_seconds between two DMs from the same sender, never less than 30 seconds.
• Daily caps: each sender has its own cap across all its campaigns, and daily_limit caps the campaign on top (see limits and sending pace).
• Follow-ups are sent by the same account that sent the previous step, and only if the person hasn't replied. If that account is disconnected, the follow-up waits for it.
• Lifecycle: if every sender of a running campaign disconnects, the campaign is paused automatically — with no webhook — and stays paused until you call resume (or start). completed means nothing is pending right now; the campaign reopens, with a new campaign.started, when follow-ups come due, when you add targets while one of its senders is connected, or when you call start or resume while it still has pending targets.
• Progress: GET /v1/campaigns/{id} returns live stats. sent counts target rows, follow-up steps included; replied counts people, and reply_rate is replied ÷ people contacted. GET /v1/campaigns/{id}/targets?status=failed lists the failures.

What does "sent" mean, and how do sends fail?

Each target moves from pending to processing and ends as sent, failed or skipped. Every follow-up step is its own target, with its own tgt_ ID and a step number. Watch them with the target.sent, target.failed and target.skipped webhooks, or list them with GET /v1/campaigns/{id}/targets?status=failed. A reply doesn't change a target's status — it stays sent — and is reported by the target.replied event.

For each target, the engine opens the recipient's profile, clicks Message, pastes the text and sends it. sent means TikTok accepted the message: the chat box emptied after sending, and no "not delivered" notice appeared within about 8 seconds. It is not a delivery or read receipt, and a first contact can land in the recipient's message requests rather than their main inbox. sent_at is when Hooka recorded the send.

TikTok's content block (blocked_by_platform) is detected in any language. "Not delivered" notices, including the privacy one (recipient_privacy), are recognised by their wording in the account's interface language, and Spanish, English, Portuguese, French, Italian and German are covered. Such a notice in another language, or any notice that appears later, goes undetected and the target stays sent.

Failures carry a stable error code, with details in error_message (TikTok's literal notice when there is one):

A target can also end as skipped, without anything being sent. The reason is one of suppressed (on your Do-Not-Contact list), duplicate_in_campaign, duplicate_across_campaigns, recipient_replied (a follow-up cancelled because the person replied), sender_unavailable (the account that had to send the follow-up was removed from the campaign or deleted with DELETE /v1/senders/{id}), missing_variable or empty_message.

Limits and sending pace

Daily caps count attempts, blocked and unconfirmed ones included, except when nothing was typed. A sender's sent_today counts only successful sends, so an account can stop for the day before sent_today reaches its daily_limit. The day is counted in UTC. With an active subscription there is no monthly DM cap.

What the API doesn't do

Better to know before you integrate:

• There is no sandbox or test mode. hk_test_ keys only read; every write acts on real accounts.
• Campaigns can't be edited or deleted through the API (there is no PATCH or DELETE /v1/campaigns/{id}), and their senders can't be changed after creation. That's done in the dashboard. The texts, senders, spacing and daily cap you change there show up in the API, but some dashboard-only options apply even though settings doesn't show them: time-window pacing (it replaces rate_limit_seconds and only sends inside the window), follow before DM (it raises the minimum spacing to 60 s and, if the account hits its following cap, it can pause the campaign) and per-account deduplication (dedupe_across_campaigns still reads true).
• An account's country can't be changed after you connect it (Hooka support can move it), and the per-account daily cap and warm-up are set only in the dashboard.
• No event when a campaign is paused, or resumed from paused. If every sender of a running campaign disconnects, the campaign pauses itself, with no webhook, and doesn't resume on its own when you reconnect: call resume.
• completed isn't final: the campaign goes back to running (with another campaign.started) when the next follow-up comes due, when you add targets while one of its senders is connected, or when you call start or resume while it still has pending targets.
• Replies you send through the API fire no events. POST /v1/conversations/{id}/messages returns 202 and the reply is queued, with no sent or failed event. A conversation's status (interested, archived…) is read-only.
• Someone who failed or was skipped can't be added again to the same campaign, and removing them from the Do-Not-Contact list doesn't revive their targets.
• One account connection at a time per workspace, as explained in the quickstart.

Building with AI agents? Use the MCP server

Hooka's remote MCP server, at https://mcp.hooka.to/mcp, exposes this same API as tools for MCP clients. Clients that connect with OAuth 2.1 (for example, Claude or ChatGPT custom connectors) sign in with your Hooka account; clients that allow headers, such as Claude Code or Cursor, can send Authorization: Bearer hk_live_.... The rules are the same: hk_test_ keys only read, and MCP requests count toward the same 300-per-minute workspace limit. An OAuth token has the same access as an hk_live_ key, except for managing API keys. More on the Hooka MCP server page.

Frequently asked questions

Keep reading