# Invite Your Team Source: https://docs.tuco.ai/account/team-members Add teammates to your Tuco workspace: invite by email from Settings → Team, choose Admin or Member, and map CRM owners so messages come from the right rep. **To add a teammate, go to Settings → Team, enter their email, pick a role (Admin or Member), and send the invite.** If they already have a Tuco account they're added to your workspace instantly; if not, they get an email with a link to join. Only workspace **Admins** can invite. ## Invite a teammate **1. Open Settings → Team** In the dashboard, go to **Settings** and open the **Team** tab. (You must be an Admin to see the invite controls.) **2. Enter email and pick a role** Type the teammate's email address and choose a role: * **Admin** — can manage the team, settings, lines, and billing. * **Member** — can use the workspace (leads, inbox) without admin controls. **3. Send the invite** Click invite. What happens next depends on whether they already use Tuco: * **Existing Tuco user** → added to your workspace immediately. * **New user** → receives an email invitation with a link to join. The pending invite (and its link) shows in your Team tab until they accept. ## Roles | Role | Can do | | - | - | | **Admin** | Everything a Member can, plus invite/remove teammates, manage lines, settings, and billing. | | **Member** | Use the workspace day-to-day — leads, the inbox, and sending. | ## Make messages come from the right rep Once teammates are in the workspace, map your CRM owners to them so each lead's outreach is attributed to the correct person: * **HubSpot** — map `hubspot_owner_id` to Tuco members in [Integrations → CRM → Owner Mapping](/integrations/hubspot#owner-mapping). Tuco also auto-matches by email when a new member joins. * **GoHighLevel** — map GHL users to Tuco members the [same way](/integrations/ghl#owner-mapping). ## Frequently asked questions > [accordion] Who can invite teammates? > > Only workspace Admins. Members can use the workspace but can't invite or remove people. > [accordion] My teammate didn't get the invite email. > > Check the pending invitation in Settings → Team — it includes a join link you can copy and send them directly. Ask them to check spam, and confirm the email address is correct. > [accordion] What's the difference between Admin and Member? > > Admins manage the team, lines, settings, and billing. Members can use the workspace (leads, inbox, sending) but can't change team or account settings. > [accordion] Can I change a teammate's role later? > > Yes — manage existing members from the Team tab. If you need help, contact [support@tuco.ai](mailto:support@tuco.ai). # Events, Metrics & Dashboards Source: https://docs.tuco.ai/analytics/events-and-metrics Understanding what Tuco AI makes visible about performance, usage, and outcomes. Reporting + observability for outbound iMessage on Tuco AI. ## What You Can See Tuco AI gives you clear, high‑level visibility into how your outreach is performing: * Overall message activity and status. * Outreach performance over time. * Line usage patterns and basic health indicators. * Reply counts and conversation volume. The system automatically handles the underlying tracking so that you can focus on reading and interpreting results in your own tools. *** ## Message Insights For messages, Tuco AI surfaces information that helps you understand: * How many messages are being sent. * How often messages reach recipients. * How frequently people respond. Data is preserved safely so you can look back over previous periods and compare them without worrying about hidden changes in behavior. *** ## Line Usage & Capacity Tuco AI makes it easy to see whether your lines are being lightly used or heavily used. You can view simple indicators that show how active each line is and how that changes over time, so you can make confident decisions about when to add capacity or rebalance usage. No action is required from you to keep these views up to date. *** ## Using Tuco Data in Your Dashboards You can bring Tuco AI data into your own BI or analytics tools and treat it like any other stable source in your reporting stack. Once connected, your dashboards continue to receive the same types of high‑level information, even as Tuco evolves internally. If you are designing a new dashboard around Tuco, focus on showing: * Overall volume trends. * Line usage and reliability at a glance. * Conversation and reply volume. The system automatically handles the details behind these numbers. *** ## Advanced Analytics (Coming Soon) Richer, out‑of‑the‑box analytics experiences inside Tuco AI are **Coming Soon**. These will focus on giving you clearer summaries and comparisons without requiring you to understand or manage any technical implementation details. # Export & Data Integration Source: https://docs.tuco.ai/analytics/export-strategies How Tuco AI works with your own reporting and BI tools. Reporting + observability for outbound iMessage on Tuco AI. ## Overview Tuco AI is designed to sit alongside your existing reporting, BI, and data tools. You can safely move Tuco data into your own systems using the export options and documented interfaces available in your Tuco workspace. No additional behavior changes are required inside Tuco once you have connected it to the destinations you control. *** ## What You Can Export > [!TIP] > > Looking for a one-click download? The **Export All Data** button on the Activity Log page gives you your full Unibox conversation history and activity events as CSV files — see [Export All Data (CSV)](/features/export-data). You can access and move the following types of information into your own systems: * Message information (such as status and basic metadata) * Lead information (such as contact details and attributes you store) * Line information (such as basic configuration and usage indicators) This data can then be combined with your existing CRM or product data in any way that suits your business. *** ## How It Feels to Use Once connected, Tuco AI behaves like a stable data source in your stack: * Data is available for reporting in your own tools * Historical information remains available for analysis * No action is required from you when Tuco makes internal improvements If you change how your own reporting environment is set up, Tuco continues to present the same predictable information for you to consume. *** ## Reliability & Safety Tuco AI is built so that exported data can be trusted for long‑term analysis. Data is preserved safely, and changes inside Tuco are designed so that your established exports keep working as communicated in product updates. If you need help designing a reporting setup around Tuco, our team can share high‑level examples of how other customers bring Tuco data into their own tools, without exposing any internal implementation. # Agency API Keys Source: https://docs.tuco.ai/api-reference/agency-api-keys The tucoagency_ key lets an agency create workspaces, move lines between them and read stats across the whole group from one credential — without signing in. If you run several Tuco workspaces under one agency account, an **agency API key** lets you manage the whole group from one credential: create a workspace for a new client, move a line between clients, and pull numbers across every workspace — without signing in and without juggling one key per workspace. > [!NOTE] > > Agency API keys are only available on agency accounts. If you have a single > workspace, use a normal [workspace API key](/api-reference/api-keys) — it already > does everything you need. ## The two kinds of key Tuco has two API keys and they are not interchangeable. You can tell them apart by the prefix. | | Workspace key | Agency key | | - | - | - | | Prefix | `tuco_…` | `tucoagency_…` | | Scope | one workspace | every workspace in your agency | | Created from | Integrations → API keys, in that workspace | Agency view → Settings → API key | | Who can create it | workspace owner or admin | the **agency owner** only | | Works on | every documented endpoint | the five agency endpoints below, and nothing else | A workspace key sent to an agency endpoint is refused with `AGENCY_KEY_REQUIRED`, and an agency key sent anywhere else is refused with `AGENCY_KEY_WRONG_ENDPOINT`. Neither is a silent failure — the error tells you which key to use. ## Creating an agency key 1. Open the **agency view** (the workspace switcher → *Agency view*). 2. Go to **Settings → API key**. 3. Give the key a name and press **Create agency key**. 4. Copy the key. It is shown once and never again. Only the agency owner sees this screen. Agency co-admins can use the agency dashboard but cannot create, list or revoke agency keys. Revoking is immediate: press **Revoke** and the key stops working on the next request. ## What an agency key can do ``` GET /api/agency/subaccounts list the workspaces in your agency POST /api/agency/subaccounts create a workspace GET /api/agency/lines list every line across the agency POST /api/agency/lines move a line between your workspaces GET /api/agency/overview stats across all sub-workspaces GET /api/agency/email-preferences who gets Tuco emails, per workspace POST /api/agency/email-preferences turn Tuco's emails off across the group GET /api/agency/webhooks every client webhook, and who has none POST /api/agency/webhooks register one for a client — or all of them DELETE /api/agency/webhooks/{id} remove one POST /api/agency/billing/subscribe put a client on a plan (no checkout page) ``` That is the whole list. An agency key cannot send a message, upload a lead, read a conversation, manage your card or create another API key. For any of that, use the workspace key for the workspace you mean. ## What an agency key deliberately cannot do * **Leave your group.** Every workspace id you pass is checked against your agency. Another agency's workspace is refused, and another agency's key cannot touch yours. * **Delete anything.** Deleting a line is reversible only by re-provisioning it, so it stays on a signed-in agency-owner session. An agency key moving a line is safe: one more call moves it back. * **Create or revoke API keys.** Key management is session-only, so a leaked key cannot be used to issue more keys. * **Touch your card or your members.** `/api/agency/billing`, `/api/agency/members` and `/api/agency/admins` stay in the dashboard. The key can subscribe a client to a plan on the card, but cannot change the card. * **Reach outside your own agency.** Lines move between YOUR workspaces. Moving one to a different agency is not something either side can do — that still comes to us. ## Authentication Send the key as a bearer token, exactly like a workspace key: ```bash theme={null} curl https://app.tuco.ai/api/agency/overview \ -H "Authorization: Bearer tucoagency_xxxxxxxxxxxxxxxx" ``` Unlike workspace keys, agency keys are **not** accepted via HTTP Basic auth — a group-wide credential travels in the `Authorization` header only. ## Two ways your agency pays | | Stripe billing (default) | Invoice billing | | - | - | - | | Who pays | Your saved card, charged per client subscription | Tuco invoices your agency offline | | `subscribe` returns | a real `subscriptionId` | `subscriptionId: null`, `billingMode: "invoice"` | | Card required | yes | no | | Client in Stripe | yes, its own subscription | **no — not at all** | | Can a client be dunned or emailed about payment? | yes, through your card | **no. There is nothing in Stripe to fail** | | Add-on lines | charged to your card | granted, added to your agency invoice | Both modes still put every client on a **plan** — that's what grants its line limits, not the charge. Invoice billing is arranged with Tuco; it is not self-serve. ## Errors | Status | Code | When | | - | - | - | | `401` | `UNAUTHORIZED` | No key, or a key that is unknown, revoked or expired | | `403` | `AGENCY_KEY_REQUIRED` | A workspace key (`tuco_…`) was sent to an agency endpoint | | `403` | `AGENCY_KEY_WRONG_ENDPOINT` | An agency key was sent to a non-agency endpoint. The body lists the endpoints it does work on | | `403` | `NOT_AN_AGENCY` | The account behind the key is no longer an agency | | `403` | `AGENCY_OWNER_REQUIRED` | A co-admin tried to manage agency keys | | `403` | `AGENCY_DELETE_SESSION_ONLY` | `action: "delete"` was attempted with an API key | A `AGENCY_KEY_WRONG_ENDPOINT` response tells you what to do next: ```json theme={null} { "error": "An agency API key only works on the agency endpoints: GET /api/agency/subaccounts, POST /api/agency/subaccounts, GET /api/agency/lines, POST /api/agency/lines, GET /api/agency/overview. Use a workspace API key (tuco_…) for /api/messages and every other endpoint.", "code": "AGENCY_KEY_WRONG_ENDPOINT", "agencyEndpoints": [ "GET /api/agency/subaccounts", "POST /api/agency/subaccounts", "GET /api/agency/lines", "POST /api/agency/lines", "GET /api/agency/overview", "GET /api/agency/email-preferences", "POST /api/agency/email-preferences", "GET /api/agency/webhooks", "POST /api/agency/webhooks", "DELETE /api/agency/webhooks/{id}", "POST /api/agency/billing/subscribe" ], "requestedPath": "/api/messages" } ``` ## A typical onboarding script Create the client's workspace, then mint a workspace key inside it from the dashboard to do the day-to-day sending. ```bash theme={null} AGENCY_KEY="tucoagency_xxxxxxxxxxxxxxxx" # 1. Create the workspace. The response also carries a ready-to-use # workspace key (tuco_...) for the new workspace — save it, it is # shown once. CREATED=$(curl -s https://app.tuco.ai/api/agency/subaccounts \ -H "Authorization: Bearer $AGENCY_KEY" \ -H "Content-Type: application/json" \ -d '{"name":"Acme Roofing","legalName":"Acme Roofing LLC","timezone":"America/Denver"}') WS=$(echo "$CREATED" | jq -r '.subAccount.clerkOrgId') WS_KEY=$(echo "$CREATED" | jq -r '.workspaceApiKey') # 2. Put them on a plan — one call, charged to your card, no checkout page curl -s https://app.tuco.ai/api/agency/billing/subscribe \ -H "Authorization: Bearer $AGENCY_KEY" \ -H "Content-Type: application/json" \ -d "{\"workspaceId\":\"$WS\",\"plan\":\"starter\"}" # 3. Move a spare line into it curl -s https://app.tuco.ai/api/agency/lines \ -H "Authorization: Bearer $AGENCY_KEY" \ -H "Content-Type: application/json" \ -d "{\"action\":\"transfer\",\"lineId\":\"6a3d7d7ef8c81f91304ed6f1\",\"targetWorkspaceId\":\"$WS\"}" # 4. Register their webhook — no need to hold their key curl -s https://app.tuco.ai/api/agency/webhooks \ -H "Authorization: Bearer $AGENCY_KEY" \ -H "Content-Type: application/json" \ -d "{\"workspaceId\":\"$WS\",\"url\":\"https://yourapp.com/hooks/tuco\",\"events\":[\"message.reply\"],\"name\":\"Acme\"}" # 5. Invite the client in, using the workspace key you just got curl -s https://app.tuco.ai/api/team/invite \ -H "Authorization: Bearer $WS_KEY" \ -H "Content-Type: application/json" \ -d '{"email":"owner@acmeroofing.com","role":"org:admin"}' # 6. Stop Tuco emailing your clients directly curl -s https://app.tuco.ai/api/agency/email-preferences \ -H "Authorization: Bearer $AGENCY_KEY" \ -H "Content-Type: application/json" \ -d '{"enabled":false}' # 7. Check in on everyone next month curl -s "https://app.tuco.ai/api/agency/overview?days=30" \ -H "Authorization: Bearer $AGENCY_KEY" ``` # Analytics Source: https://docs.tuco.ai/api-reference/analytics Workspace analytics endpoint — reached, sent, replied, reply %, positive %, filterable by sender line, user, and date window. ## Overview `GET /api/analytics` returns one consolidated metric block for your workspace, filterable down to a single sender line, sending user, or date window. The same numbers power the **/analytics** page in the dashboard and the `analytics` MCP tool, so a UI chart, an MCP question, and a curl call all agree. > [!NOTE] > > Reply rate and positive rate are computed as **unique-by-contact** ratios. > A contact who got 5 messages still counts as 1 toward "reached", and one > contact who replies 10 times still counts as 1 toward "uniqueReplied". *** ## Endpoint ``` GET https://app.tuco.ai/api/analytics ``` ### Authentication Bearer-token. Pass your API key (`tuco_...`) in the `Authorization` header: ```bash theme={null} curl -H "Authorization: Bearer tuco_..." https://app.tuco.ai/api/analytics ``` ### Query parameters **lineId** `string` Restrict to a single sender line (MongoDB ObjectId as 24-char hex). **userId** `string` Restrict to a single Clerk user ID who created the messages (`user_…`). **dateFrom** `string` Inclusive lower bound, ISO 8601 (e.g. `2026-06-01T00:00:00Z`). Filters on `message.createdAt`. **dateTo** `string` Inclusive upper bound, ISO 8601. **agencyId** `string` Reserved for the multi-workspace agency rollup that ships later. Today the endpoint returns **501 Not Implemented** if this parameter is supplied; call without it to get your own workspace's numbers. All filters are intersected. Omit a filter to remove that constraint. *** ## Response ```json theme={null} { "success": true, "filter": { "lineId": "60d5ec49e3a8a0001f9b1234", "dateFrom": "2026-06-01T00:00:00.000Z" }, "metrics": { "reached": 1245, "sent": 3870, "fallback": 92, "failed": 14, "replied": 418, "uniqueReplied": 312, "repliedPct": 0.2506, "positiveReplied": 71, "positivePct": 0.2275 }, "explainer": { "reached": "Unique contacts that received at least one outbound message (status sent or delivered).", "sent": "Total outbound messages with status sent or delivered. One contact may count more than once.", "fallback": "Outbound messages that fell back to SMS or could not be sent via iMessage.", "failed": "Outbound messages that hit a hard send failure (technical error, blocked recipient, etc.).", "replied": "Total inbound messages from contacts in the window.", "uniqueReplied": "Distinct contacts that replied at least once.", "repliedPct": "uniqueReplied / reached. Reply rate by unique contact.", "positiveReplied": "Distinct contacts whose conversation carries a positive tag (interested, to respond, to-answer).", "positivePct": "positiveReplied / uniqueReplied. Share of replies that are warm." } } ``` ### Metric definitions **reached** `number` Distinct contacts (phone or email) that received at least one outbound message with status `sent` or `delivered` inside the filter window. **sent** `number` Total outbound messages with status `sent` or `delivered`. Not de-duplicated by contact — 7 messages each to 1,000 contacts can show `sent ≈ 7,000`. **fallback** `number` Outbound messages with status `fallback` **or** with `fallbackSmsDispatched` set. Both signal iMessage didn't go through and SMS was attempted instead. **failed** `number` Outbound messages with status `failed` — hard send failure (technical error, blocked recipient, transient-exhausted, etc.). **replied** `number` Total inbound messages received inside the filter window. Includes multiple replies from the same contact. **uniqueReplied** `number` Distinct contacts that replied at least once inside the window. **repliedPct** `number` `uniqueReplied / reached`. A decimal between 0 and 1 (multiply by 100 for the display %). Returns 0 when `reached` is 0 — never divides by zero. **positiveReplied** `number` Distinct contacts among `uniqueReplied` whose conversation document carries at least one positive tag: `interested`, `to respond`, `to-answer`, or `to_answer` (case-insensitive exact match). Tags are written by Tuco's reply classifier and by Unibox operators. **positivePct** `number` `positiveReplied / uniqueReplied`. Share of repliers tagged warm. Returns 0 when `uniqueReplied` is 0. *** ## Error responses | Status | Code | When | | - | - | - | | `401` | `Unauthorized` | Missing or invalid API key / Clerk session | | `501` | `AGENCY_NOT_AVAILABLE` | `agencyId` filter supplied — feature not yet shipped | | `500` | — | Aggregation failed; check the message status for the `analytics.error` event | *** ## Example: pull last-30-day numbers for one line ```bash theme={null} curl -s -H "Authorization: Bearer tuco_..." \ "https://app.tuco.ai/api/analytics?lineId=60d5ec49e3a8a0001f9b1234&dateFrom=$(date -u -v-30d +%Y-%m-%dT00:00:00Z)" \ | jq '.metrics' ``` ## Example: via MCP Configure the [Tuco MCP server](/integrations/mcp-server) and ask any MCP-compatible AI assistant: > "Show analytics for line `60d5ec49e3a8a0001f9b1234` over the last 30 > days." The assistant calls the `analytics` MCP tool, which hits this endpoint with your API key and returns the same metric block. ## Observability Every successful call records a structured `analytics.served` event internally: ```json theme={null} { "event": "analytics.served", "workspaceId": "org_…", "authMethod": "api_key", "filter": { "lineId": "…", "dateFrom": "…", "dateTo": "…" }, "metrics": { /* the full block */ }, "durationMs": 101 } ``` Failures emit `analytics.error` with the error message and workspace id. # Tuco API Keys Source: https://docs.tuco.ai/api-reference/api-keys Where to find your Tuco API key and how bearer-token auth is used to authenticate every request to the Tuco iMessage API. ## Where the API Key Lives Every Tuco workspace can have one or more API keys managed from within the product. In practice, this means: * Workspace owners and admins control which keys exist. * Keys can be created, renamed, or removed without affecting existing data. * Each key is clearly labeled so you know which environment or integration it is for. If you do not see an API key in your workspace, your Tuco admin can enable one for you. *** ## How the Key Is Used The Tuco API key is used as the single piece of authorization information on all server‑side API calls. From your point of view: * The same key works across all documented Tuco API endpoints. * Requests made with this key either succeed with clear confirmation or are rejected with an explicit error. * Disabling or rotating a key immediately stops further access with the old value. No additional tokens from external identity providers are required when calling the Tuco API from your backend. *** ## Finding or Rotating Your Key You never need to touch any internal systems to manage your Tuco API key. Instead: * Keys are created and rotated entirely from your Tuco workspace settings. * Changes take effect right away for all future calls that use the new value. * Old keys can be removed when no longer needed, without changing any of your stored data. If you are unsure who controls API keys for your company, check with your Tuco workspace owner or administrator. *** ## FAQs **How do I get an API key for the first time?** Your Tuco workspace comes with the ability to create an internal API key from within the product. A workspace owner or admin can generate one and share it with your engineering team using your usual secure channels. **Can I have separate keys for staging and production?** Yes. You can maintain multiple keys and decide which one each environment should use. The system automatically treats all valid keys for a workspace the same way from an access perspective. **What happens if my key is exposed?** You can immediately rotate or revoke the key from your Tuco workspace. New calls with the old key will stop working, and your existing data remains preserved safely. # Drip (bulk shock-absorber) Source: https://docs.tuco.ai/api-reference/drip POST /api/drip — same body as /api/messages, never 429s a bulk blast, fast-acks 202, and drips sends safely per line. Built for CRM enrollment fan-out. ## Overview `POST /api/drip` is a per-request intake endpoint that accepts the **exact same body as [`POST /api/messages`](/api-reference/messages)** but is built for **bulk, bursty** traffic — HubSpot and other CRMs fan enrollments out in parallel and retry any `429`/timeout for up to 3 days, which turns a rate limit into a retry storm and duplicate sends. `/api/drip` solves that: * **Never rate-limited.** It is exempt from the 60/min send limiter, so a blast is never rejected with `429` (an infra backstop exists only for runaway abuse — see [Limits](#limits)). * **Fast-acks `202`** in well under 2 seconds. * **Drips safely.** Every accepted message is inserted as a **jittered scheduled send**, then the existing worker + per-line **ban protector** pace the real sends so a line is never pushed past its safe cadence (which is what protects your iMessage lines from Apple). > [!NOTE] > > **To switch a HubSpot/CRM integration from `/api/messages` to `/api/drip`, change > ONLY the URL you POST to.** The request body, auth, and per-request contract are > identical. Use `/api/drip` for bulk enrollment blasts; keep `/api/messages` for > low-volume, send-now traffic where you want the immediate delivery status back. *** ## When to use which | | `POST /api/messages` | `POST /api/drip` | | - | - | - | | Best for | Interactive / low-volume send-now | Bulk, bursty CRM enrollment fan-out | | Rate limit | 60 req/min per workspace (`429` past that) | **None** (infra backstop only) | | On success | May send synchronously; returns real status | Always scheduled; returns `202 queued` | | Delivery pacing | Immediate (subject to line caps) | Jittered + ban-protector paced per line | | Response | `201` with the message object | `202 { status, correlationId, scheduledDate }` | *** ## Request `POST https://app.tuco.ai/api/drip` **Auth:** `Authorization: Bearer ` (same key as `/api/messages`; a Clerk session also works). **Method:** `POST` only. **Body:** the same per-message shape as [`POST /api/messages`](/api-reference/messages#request). The delivery/routing fields are forwarded verbatim: `message`, `messageType`, `recipientPhone` / `recipientEmail` / `recipientName`, `leadId`, `hsContactId` / `hsPortalId`, `ghlContactId` / `ghlLocationId`, `pdCompanyId` / `pdPersonId` / `pdLeadId`, `attachmentUrls` / `attachmentNames`, `sendFallbackSmsOnFailed` / `smsFallbackEnabled` / `smsFallbackMessage` / `forceFallback`, `correlationId` / `traceId`, and the send-window settings `timezone` / `sendWindowStart` / `sendWindowEnd` / `allowedDaysOfWeek` (honored — a message is clamped into your window before it drips). > [!NOTE] > > Orchestration fields are **not** applied by `/api/drip` (it is a > per-message shock-absorber): `batchId`, `stepIndex`, > `eligibleLineIds`, `stickinessPolicy`, the failover knobs, `isAgentDriven`, and > `needsAiPersonalization` are ignored. Two fields are managed **for** you and cannot be set: * **`scheduledDate`** — always overwritten with a jittered future time (min now * 30s, spread over \~5 min) so the send is queued, never fired at intake. Any `scheduledDate` you pass is ignored. * **Line selection** — if you omit `fromLineId`, a line is chosen by the same workspace round-robin `/api/messages` uses (a persisted, workspace-wide rotation so no single line is hammered). An explicit `fromLineId` is honored and validated to your workspace. **Idempotency-Key** `string` Optional. HubSpot retries **will** resend — pass a stable per-message `Idempotency-Key` and a retry returns the original `202` instead of queueing a second message. Even without it, an atomic 60-minute dedup guard on `(workspace, recipient, body)` collapses accidental duplicates. ### Example ```bash theme={null} curl -X POST https://app.tuco.ai/api/drip \ -H "Authorization: Bearer $TUCO_API_KEY" \ -H "Content-Type: application/json" \ -H "Idempotency-Key: hs-enroll-8471-step2" \ -d '{ "message": "Hi Jane — following up on your quote.", "recipientPhone": "+14155551234", "hsContactId": "8471", "hsPortalId": "1234567" }' ``` *** ## Response `202 Accepted` — fast-ack. The request is buffered and the message is created a moment later, then sent still later (paced per line). See below. ```json theme={null} { "status": "queued", "correlationId": "drip_1783787897123_a1b2c3", "scheduledDate": "2026-07-11T18:32:07.412Z", "jitterMs": 127412 } ``` **status** `string` Always `"queued"`. **correlationId** `string` Tracking id for this request (echoed from your `correlationId` / `X-Correlation-Id` if you sent one). The message itself is created shortly after the ack, so no `messageId` is returned here — grep this id in your webhook payloads to correlate. **scheduledDate** `string` ISO 8601 — the jittered future time the message becomes eligible to send. If you set a send window it is clamped into it; the ban protector may push it later still at drain time if the line is at its daily cap. **jitterMs** `number` The jitter applied over the +30s floor, for observability. A duplicate (same `Idempotency-Key`) returns `200` with the original ack — no second message. Same-content duplicates `(workspace, recipient, body)` within 60 minutes are also collapsed to one message downstream. ### What happens next The intake is **buffered** (Redis): it accepts your blast instantly and never touches the database on the request path, so it absorbs large parallel bursts. A paced worker then drains the buffer at a database-safe rate and creates each message as a **scheduled** send (`source: "hubspot-drip"`), visible in **Unibox → Scheduled**. At each message's scheduled time the per-line **ban protector** allows it only if the line is under its caps and pacing (150 messages/day and 50 new contacts/day by default; new contacts at most 5/min and 15/hr, other messages at most 10/min and 40/hr) and otherwise **reschedules** it (pacing → seconds to minutes, hourly cap → next hour, daily cap → next workspace morning). Two independent throttles — buffer→database, then database→Apple — so a burst in never becomes a burst out. Nothing is dropped. Delivery status flows through the same [message webhooks](/api-reference/message-webhooks) as `/api/messages`. *** ## Limits `/api/drip` is **not** subject to the 60/min send limit and will not `429` a normal blast. The only limit is a high **infra backstop** on the buffered intake: \~1,000 requests/sec sustained per workspace (a 10,000-request burst bucket). It trips solely on runaway/abuse; if you ever hit it you receive `429` + `Retry-After` and can retry safely. Because the intake is buffered, database write pressure is governed by the paced drainer, not by how fast you post. | Limit | Value | | - | - | | Body | Single message per request (same shape as `/api/messages`) | | Rate limit | **None** — exempt from the 60/min send limiter (infra backstop only) | | Infra backstop | \~1,000 req/sec sustained / 10,000 burst per workspace → `429` + `Retry-After` on runaway | | Real send pacing | Per line: 150 messages/day and 50 new contacts/day by default; new contacts ≤5/min and ≤15/hr, other messages ≤10/min and ≤40/hr. See [rate limits](/features/rate-limits) | | Ack | `202 { status, correlationId, scheduledDate }` in \< 2s | | Auth | API key (Bearer) or Clerk | | Dedup | `Idempotency-Key`, plus atomic `(workspace, recipient, body)` 60-min guard | See [Errors & rate limits](/api-reference/errors) for the full table. # Add to Do-Not-Contact Source: https://docs.tuco.ai/api-reference/endpoint/add-dnc POST /api/dnc Add a phone number or email to your workspace's Do-Not-Contact list so Tuco never messages it. REST endpoint in the Tuco AI iMessage API — bearer-token auth. > [!NOTE] > > Use this to push opt-outs from your other channels (WhatsApp, email, forms) into Tuco. Every message is checked against this list before it is sent. A successful add fires the [`dnc.added` webhook](/api-reference/message-webhooks#dnc-added). ## Authentication ```bash theme={null} Authorization: Bearer tuco_xxxxxxxxxxxxx ``` ## Example ```bash theme={null} curl -X POST "https://app.tuco.ai/api/dnc" \ -H "Authorization: Bearer tuco_xxxxxxxxxxxxx" \ -H "Content-Type: application/json" \ -d '{ "phone": "555-010-0778", "reason": "whatsapp-opt-out" }' ``` ## Success response (200) ```json theme={null} { "ok": true, "id": "6ad60002d963dc1e85d12148" } ``` ## Errors | Status | Body | When | | - | - | - | | `400` | `{ "error": "Either phone or email is required" }` | Neither field sent | | `400` | `{ "error": "Body must be JSON: { phone?, email?, reason? }" }` | Body is not JSON | | `401` | `{ "error": "Unauthorized" }` | Missing or invalid API key | | `409` | `{ "error": "This contact is already on the DNC list" }` | Already listed | | `429` | `{ "error": "Rate limit exceeded" }` | Rate limit exceeded | To add many contacts at once, use [Bulk add](/api-reference/endpoint/bulk-add-dnc). Removing a contact from the list is done in the dashboard only. # Create Agency Workspace Source: https://docs.tuco.ai/api-reference/endpoint/agency-create-workspace POST /api/agency/subaccounts Create a new client workspace inside your Tuco agency, subscribe it to a plan, and get its workspace API key back — in one call. > [!NOTE] > > Creates a workspace under your agency, optionally **subscribes it to a plan**, > and returns a ready-to-use **workspace API key** for it — so an onboarding > script never has to stop and mint a key or make a second billing call by hand. ## Endpoint * **Method**: `POST` * **Path**: `/api/agency/subaccounts` * **Auth**: `Authorization: Bearer tucoagency_xxxxxxxxxxxxx` ([agency key](/api-reference/agency-api-keys)) ## Body | Field | Type | Required | Notes | | - | - | - | - | | `name` | string | yes | Display name, max 120 characters | | `legalName` | string | no | The client's legal/LLC name, max 200 characters | | `timezone` | string | no | IANA zone (e.g. `America/Denver`). Sets the daily-cap reset window. Invalid zones are rejected with `400` | | `plan` | string | no | `starter` or `growth`. Subscribes the workspace in the same call — see below. Omit to create it unsubscribed | ## Example request ```bash theme={null} curl https://app.tuco.ai/api/agency/subaccounts \ -H "Authorization: Bearer tucoagency_xxxxxxxxxxxxx" \ -H "Content-Type: application/json" \ -d '{ "name": "Acme Roofing", "legalName": "Acme Roofing LLC", "timezone": "America/Denver", "plan": "growth" }' ``` ## Success response (200) ```json theme={null} { "success": true, "subAccount": { "clerkOrgId": "org_3KKLH9HaVf4KyI6TiNhQk4T0cfa", "name": "Acme Roofing", "agencyId": "user_3H08IRicrVUYLDZRyOh4jKRVwrx", "isAgencyWorkspace": true }, "workspaceApiKey": "tuco_xCsfhTiXXXXXXXXXXXXXXXXXXXXXXXX", "workspaceApiKeyWarning": "Save this workspace key now. You will not be able to see it again.", "plan": "growth", "subscriptionStatus": "active", "billingMode": "invoice", "planError": null } ``` The last four fields appear **only when you passed `plan`**. Omit it and the response is exactly what it always was. > [!WARNING] > > `workspaceApiKey` is shown **once**. Store it when you create the workspace — it > cannot be retrieved later, only replaced from the workspace's Integrations page. It is a normal workspace key: it works on every documented endpoint for that workspace, and on no other workspace. It is **not** an agency key and cannot reach the agency endpoints. In the rare case key creation fails, the workspace is still created and `workspaceApiKey` is `null` — make one from the workspace's Integrations page. ## Subscribing in the same call A plan is not optional in practice. `plan` is what grants a workspace its line limits, and an agency workspace with no plan is refused outright — a line transfer into one fails. So every onboarding script made the second call anyway. `plan` on create collapses the two. | Plan | | | - | - | | `starter` | \$149/mo + one-time setup | | `growth` | Higher line limits | > [!NOTE] > > There is no `enterprise` plan. `email-only` (Mini) exists but is retired and is > rejected for new subscriptions. Workspaces already on it keep renewing. It runs the same billing path as [`POST /api/agency/billing/subscribe`](/api-reference/endpoint/agency-subscribe), so the behaviour matches exactly: * **Invoiced agency** — the workspace gets the plan and **no card is charged**. `billingMode: "invoice"`, and no Stripe subscription exists for it, which is what makes your client structurally unreachable by dunning and payment mail. **Line caps do not apply either** — see below. * **Stripe agency** — your saved card is charged off-session, as it would be on the standalone route. `billingMode: "stripe"`. ### An invalid plan is rejected before anything is created ```json theme={null} { "error": "Unknown plan \"enterprise\".", "code": "INVALID_PLAN", "validPlans": ["starter", "growth"] } ``` `400`, and **no workspace exists** — the plan is validated before the workspace is created, so a typo cannot leave an orphan behind. ### A billing failure does not lose the workspace If the plan cannot be applied *after* the workspace exists — a declined card, Stripe unreachable — you still get `200`, the workspace, and its key: ```json theme={null} { "success": true, "subAccount": { "clerkOrgId": "org_3KKLH9HaVf4KyI6TiNhQk4T0cfa", "…": "…" }, "workspaceApiKey": "tuco_xCsfhTiXXXXXXXXXXXXXXXXXXXXXXXX", "plan": null, "subscriptionStatus": "none", "planError": "Your card was declined." } ``` Failing the whole request would hide a workspace that already exists and get you a duplicate on retry. **Check `planError`**, then retry the billing step alone with [`POST /api/agency/billing/subscribe`](/api-reference/endpoint/agency-subscribe) — do not create the workspace again. ### If Tuco invoices your agency, lines are uncapped Plan line limits exist to meter what a card gets charged for. When Tuco invoices your agency offline for the whole group, there is nothing for them to meter — they can only block a line you have already agreed to pay for. So for an invoiced agency, **every client workspace can order any number of lines**, whatever plan it carries. It applies to all three paths — [ordering a line](/api-reference/endpoint/create-line-request), [creating one directly](/api-reference/lines), and the [capacity the dashboard reports](/api-reference/endpoint/line-limits), which returns `unlimitedReason: "invoiced_agency"`. > [!NOTE] > > This is a commercial arrangement, not a setting. Tuco switches it on per agency, > the same switch that enables [line-health webhooks](/api-reference/endpoint/agency-webhooks). > On Stripe billing, normal plan caps apply and extra lines are add-on purchases. You still pass a `plan`: it is what sets the workspace's message throughput and what marks it active. It just stops being a ceiling on lines. ## What the new workspace starts as * Owned by your agency (`isAgencyWorkspace: true`) — it has no card of its own and bills through you. * `subscriptionStatus: "active"` when you passed a plan, `"none"` otherwise. Subscribe it before moving lines in; a transfer into an unsubscribed workspace is refused. * You and your agency co-admins are admins on it, so it appears in the workspace switcher immediately. * It has its own workspace API key, returned above. ## Error responses | Status | Code | When | | - | - | - | | `400` | — | `name` missing, or `timezone` is not a valid IANA zone | | `400` | `INVALID_PLAN` | Unknown `plan`. The body lists `validPlans` | | `400` | `RETIRED_PLAN` | `plan: "email-only"` — Mini is retired for new subscriptions | | `401` | `UNAUTHORIZED` | Missing, unknown, revoked or expired key | | `403` | `AGENCY_KEY_REQUIRED` | A workspace key (`tuco_…`) was used | | `403` | `NOT_AN_AGENCY` | The account behind the key is not an agency | # Agency Email Preferences Source: https://docs.tuco.ai/api-reference/endpoint/agency-email-preferences POST /api/agency/email-preferences Turn Tuco's notification emails (reply alerts, billing and error notices) off or back on across every workspace in your agency, or in one, in one call. > [!NOTE] > > Your clients live inside your sub-workspaces. This stops Tuco emailing them > directly — reply alerts, billing notices, error notices — across the whole > group, or in one workspace, or for one email type. ## Endpoint * **Method**: `POST` (read the current state with `GET` on the same path) * **Path**: `/api/agency/email-preferences` * **Auth**: `Authorization: Bearer tucoagency_xxxxxxxxxxxxx` ([agency key](/api-reference/agency-api-keys)) ## Body | Field | Type | Required | Notes | | - | - | - | - | | `enabled` | boolean | **yes** | `false` silences, `true` re-enables. No default — a body-less POST is rejected rather than guessed | | `types` | string\[] | no | Omitted = all five. One or more of `line_health`, `campaign`, `reply`, `billing`, `system_error` | | `workspaceId` | string | no | Limit to one sub-account. Omitted = every workspace in the agency | ## Silence everything, everywhere ```bash theme={null} curl https://app.tuco.ai/api/agency/email-preferences \ -H "Authorization: Bearer tucoagency_xxxxxxxxxxxxx" \ -H "Content-Type: application/json" \ -d '{"enabled": false}' ``` ```json theme={null} { "agencyId": "user_3H08IRicrVUYLDZRyOh4jKRVwrx", "enabled": false, "types": ["line_health", "campaign", "reply", "billing", "system_error"], "workspacesUpdated": 4, "membersUpdated": 11, "workspaces": [ { "clerkOrgId": "org_3KKJKupHJ8Y9I2NXVAga0c6ZqgT", "name": "Acme Roofing", "members": 3 } ] } ``` ## Narrower changes ```bash theme={null} # Only reply alerts, only in one workspace -d '{"enabled": false, "types": ["reply"], "workspaceId": "org_3KKJKupHJ8Y9I2NXVAga0c6ZqgT"}' # Put billing notices back on everywhere -d '{"enabled": true, "types": ["billing"]}' ``` ## What it does and does not touch * Preferences are per member, per workspace. The call writes **every member** of every targeted workspace, including members who had no stored preference and were therefore on the default (everything on). * Settings are **merged**, not replaced. Turning `reply` off keeps your existing `reply.mode`; turning other types off leaves `reply` alone. * **Your own agency account is not affected.** Silencing your clients does not silence you. * `line_health` is accepted for completeness, but line-down and recovery emails are governed by each line's own **Line Down Notifications** toggle, not by this preference. Turning `line_health` off here will not stop them. ## Reading the current state ```bash theme={null} curl https://app.tuco.ai/api/agency/email-preferences \ -H "Authorization: Bearer tucoagency_xxxxxxxxxxxxx" ``` ```json theme={null} { "agencyId": "user_3H08IRicrVUYLDZRyOh4jKRVwrx", "emailTypes": ["line_health", "campaign", "reply", "billing", "system_error"], "workspaces": [ { "clerkOrgId": "org_3KKJKupHJ8Y9I2NXVAga0c6ZqgT", "name": "Acme Roofing", "membersWithPreferences": 3, "anyEmailsEnabled": false, "members": [{ "userId": "user_…", "preferences": { "reply": { "enabled": false } } }] } ] } ``` A workspace with `membersWithPreferences: 0` has nobody on a stored preference, so everyone there is on the defaults — `anyEmailsEnabled` is `true`. Add `?workspaceId=org_…` to read one workspace. ## Error responses | Status | Code | When | | - | - | - | | `400` | `ENABLED_REQUIRED` | `enabled` missing or not a boolean | | `400` | `INVALID_TYPES` | `types` empty, not an array, or naming an unknown type | | `401` | `UNAUTHORIZED` | Missing, unknown, revoked or expired key | | `403` | `AGENCY_KEY_REQUIRED` | A workspace key (`tuco_…`) was used | | `403` | `NOT_YOUR_WORKSPACE` | `workspaceId` is not in your agency | | `403` | `NOT_AN_AGENCY` | The account behind the key is not an agency | # List Agency Lines Source: https://docs.tuco.ai/api-reference/endpoint/agency-list-lines GET /api/agency/lines List every iMessage/SMS/email line across all workspaces in your Tuco agency, with the workspace each one sits in. > [!NOTE] > > One view of every line your agency owns, across every workspace. Use it to find the > `lineId` you want to move. ## Endpoint * **Method**: `GET` * **Path**: `/api/agency/lines` * **Auth**: `Authorization: Bearer tucoagency_xxxxxxxxxxxxx` ([agency key](/api-reference/agency-api-keys)) ## Example request ```bash theme={null} curl https://app.tuco.ai/api/agency/lines \ -H "Authorization: Bearer tucoagency_xxxxxxxxxxxxx" ``` ## Success response (200) ```json theme={null} { "isOwner": false, "workspaces": [ { "clerkOrgId": "org_3KKJKupHJ8Y9I2NXVAga0c6ZqgT", "name": "Acme Roofing" } ], "lines": [ { "lineId": "6a3d7d7ef8c81f91304ed6f1", "workspaceId": "org_3KKJKupHJ8Y9I2NXVAga0c6ZqgT", "workspaceName": "Acme Roofing", "identifier": "+16465550100", "channelType": "phone", "lineType": "byon", "provisioningStatus": "active", "name": "Lindsey Rodriguez" } ] } ``` `isOwner` is always `false` for an API key — deleting a line requires a signed-in agency owner, so the key is told up front that the destructive action is not available to it. ## Error responses | Status | Code | When | | - | - | - | | `401` | `UNAUTHORIZED` | Missing, unknown, revoked or expired key | | `403` | `AGENCY_KEY_REQUIRED` | A workspace key (`tuco_…`) was used | | `403` | `NOT_AN_AGENCY` | The account behind the key is not an agency | # List Agency Workspaces Source: https://docs.tuco.ai/api-reference/endpoint/agency-list-workspaces GET /api/agency/subaccounts List every sub-account workspace in your Tuco agency, newest first, with the clerkOrgId other agency endpoints use. Agency API key, bearer-token auth. > [!NOTE] > > Returns the sub-account workspaces in your agency, newest first. Your agency's own > hidden root workspace is never included. ## Endpoint * **Method**: `GET` * **Path**: `/api/agency/subaccounts` * **Auth**: `Authorization: Bearer tucoagency_xxxxxxxxxxxxx` ([agency key](/api-reference/agency-api-keys)) ## Example request ```bash theme={null} curl https://app.tuco.ai/api/agency/subaccounts \ -H "Authorization: Bearer tucoagency_xxxxxxxxxxxxx" ``` ## Success response (200) ```json theme={null} { "agencyId": "user_3H08IRicrVUYLDZRyOh4jKRVwrx", "subAccounts": [ { "clerkOrgId": "org_3KKJKupHJ8Y9I2NXVAga0c6ZqgT", "name": "Acme Roofing", "legalName": "Acme Roofing LLC", "agencyName": "Flowmentum", "subscriptionStatus": "active", "createdAt": "2026-10-06T15:24:15.223Z" } ] } ``` Use `clerkOrgId` wherever another agency endpoint asks for a `workspaceId`. ## Error responses | Status | Code | When | | - | - | - | | `401` | `UNAUTHORIZED` | Missing, unknown, revoked or expired key | | `403` | `AGENCY_KEY_REQUIRED` | A workspace key (`tuco_…`) was used | | `403` | `NOT_AN_AGENCY` | The account behind the key is not an agency | # Move a Line Between Workspaces Source: https://docs.tuco.ai/api-reference/endpoint/agency-move-line POST /api/agency/lines Move an iMessage/SMS/email line from one workspace in your agency to another. Cancels anything still queued on the line. > [!WARNING] > > Moving a line **cancels every message still waiting to go out on it** — status > `queued`, `pending` or `scheduled` (scheduled is the rescheduled/retry state). > Send a `preview` first to see how many that is. ## Endpoint * **Method**: `POST` * **Path**: `/api/agency/lines` * **Auth**: `Authorization: Bearer tucoagency_xxxxxxxxxxxxx` ([agency key](/api-reference/agency-api-keys)) ## Body | Field | Type | Required | Notes | | - | - | - | - | | `action` | string | yes | `"transfer"` | | `lineId` | string | yes | From [List Agency Lines](/api-reference/endpoint/agency-list-lines) | | `targetWorkspaceId` | string | yes | A `clerkOrgId` in **your** agency | | `preview` | boolean | no | `true` returns the impact and changes nothing | ## Why queued messages are cancelled A queued message belongs to the workspace that queued it — its copy, its lead, its daily cap. If it survived the move, the **new** workspace's line would send the **old** workspace's message. Cancelling is the only correct answer; the original workspace can re-queue on a line it still owns. Messages already handed to the device (`sending`) are **not** touched — flipping them would not un-send anything. Everything already `sent`, `delivered`, `failed`, `fallback`, `cancelled` or `stopped` is untouched, and messages on **other** lines in the same workspace are untouched. Cancelled messages are stamped with `cancelReason: "line:transferred_to_other_workspace"` so the reason is visible in the unibox. ## Preview first ```bash theme={null} curl https://app.tuco.ai/api/agency/lines \ -H "Authorization: Bearer tucoagency_xxxxxxxxxxxxx" \ -H "Content-Type: application/json" \ -d '{ "action": "transfer", "lineId": "6a3d7d7ef8c81f91304ed6f1", "targetWorkspaceId": "org_3KKJL4DnbqOA406ibeGV9nOUgnk", "preview": true }' ``` ```json theme={null} { "preview": true, "chargedNowCents": 0, "monthlyDeltaCents": 0, "channel": "phone", "currency": "usd", "messagesToCancel": 5 } ``` ## Then move it ```json theme={null} { "success": true, "chargedNowCents": 0, "monthlyDeltaCents": 0, "targetAddonAdded": false, "sourceReleased": false, "cancelledMessages": 5 } ``` ## What it costs A transfer never charges or credits at the moment it happens. It shifts the line's add-on between workspaces, and the recurring amount lands on the new workspace at the next billing cycle: * Target has a free slot on its plan → no billing change at all. * Target is full → `+1` add-on on the target (`targetAddonAdded: true`), billed next cycle. * The line was a paid extra on the source → `−1` add-on there (`sourceReleased: true`), stops billing next cycle. Moving a paid line into a full workspace is a wash: `monthlyDeltaCents: 0`. ## Deleting a line `action: "delete"` exists but is **session-only**. An API key gets `403 AGENCY_DELETE_SESSION_ONLY`: deleting is irreversible, so it stays with a signed-in agency owner. Moving is safe for a key because one more call moves it back. ## Error responses | Status | Code / message | When | | - | - | - | | `400` | `Valid lineId is required` | Missing or malformed `lineId` | | `400` | `targetWorkspaceId is required` | Missing target | | `400` | `Line is already in that workspace` | Source and target are the same | | `400` | `Target workspace has no active subscription…` | Subscribe the target first | | `400` | `Target plan … doesn't support lines` | Plan cannot hold this channel | | `400` | `Target workspace is at its … limit` | Add-on hard cap reached | | `401` | `UNAUTHORIZED` | Missing, unknown, revoked or expired key | | `403` | `AGENCY_KEY_REQUIRED` | A workspace key (`tuco_…`) was used | | `403` | `That line is not part of your agency` | The line belongs to someone else | | `403` | `Target workspace is not part of your agency` | The target belongs to someone else | | `403` | `AGENCY_DELETE_SESSION_ONLY` | `action: "delete"` with an API key | | `404` | `Line not found` | Unknown `lineId` | # Agency Overview Stats Source: https://docs.tuco.ai/api-reference/endpoint/agency-overview GET /api/agency/overview Rolled-up messaging stats across every workspace in your Tuco agency, plus a per-workspace breakdown and billing health. > [!NOTE] > > One call for the whole agency: aggregate metrics, a row per workspace, line counts > and subscription health. ## Endpoint * **Method**: `GET` * **Path**: `/api/agency/overview` * **Auth**: `Authorization: Bearer tucoagency_xxxxxxxxxxxxx` ([agency key](/api-reference/agency-api-keys)) ## Query parameters | Param | Type | Notes | | - | - | - | | `days` | `7` \| `30` \| `90` | Window for the activity metrics. Omitted or invalid → all time. Line counts are current state and are never windowed | ## Example request ```bash theme={null} curl "https://app.tuco.ai/api/agency/overview?days=30" \ -H "Authorization: Bearer tucoagency_xxxxxxxxxxxxx" ``` ## Success response (200) ```json theme={null} { "agencyId": "user_3H08IRicrVUYLDZRyOh4jKRVwrx", "workspaces": 4, "totalLines": 7, "metrics": { "reached": 1840, "sent": 2190, "fallback": 61, "failed": 12, "replied": 143, "uniqueReplied": 128, "repliedPct": 6.9, "positiveReplied": 41, "positivePct": 2.2 }, "statusCounts": { "active": 3, "attention": 1, "inactive": 0 }, "series": { "days": 30, "sent": [12, 40, 0, 31] }, "perWorkspace": [ { "clerkOrgId": "org_3KKJKupHJ8Y9I2NXVAga0c6ZqgT", "name": "Acme Roofing", "legalName": "Acme Roofing LLC", "plan": "starter", "subscriptionStatus": "active", "lines": 2, "sent": 814, "received": 57, "failed": 3, "repliedPct": 7.0 } ] } ``` ## Reading it * `metrics` is the roll-up across every sub-workspace; `perWorkspace` is the same computation per workspace, so the rows sum to the totals. * `statusCounts.attention` counts workspaces in `past_due`, `unpaid`, `incomplete`, `incomplete_expired` or `canceled` — the ones whose billing needs you. * `series.sent` is a daily count for the last `days` calendar days including today, for a sparkline. * An agency with no workspaces yet returns zeros, never another agency's numbers. ## Error responses | Status | Code | When | | - | - | - | | `401` | `UNAUTHORIZED` | Missing, unknown, revoked or expired key | | `403` | `AGENCY_KEY_REQUIRED` | A workspace key (`tuco_…`) was used | | `403` | `NOT_AN_AGENCY` | The account behind the key is not an agency | # Monthly Statement Source: https://docs.tuco.ai/api-reference/endpoint/agency-statement GET /api/agency/statement What to invoice your clients this month — setup fees and prorated line charges, per client, per line. For agencies Tuco invoices offline. > [!NOTE] > > For agencies **Tuco invoices offline**. Tuco bills you for the whole group, so > your client workspaces have no card and no Stripe subscription — which leaves > you working out what to charge each client by hand. This does the arithmetic. > > It **charges nothing**. You still send your own invoice. ## Endpoint * **Method**: `GET` * **Path**: `/api/agency/statement` * **Auth**: `Authorization: Bearer tucoagency_xxxxxxxxxxxxx` ([agency key](/api-reference/agency-api-keys)) ## Query parameters | Name | Required | Notes | | - | - | - | | `month` | no | `YYYY-MM`. Defaults to the current UTC month. Anything else is a `400` | | `format` | no | `csv` for a spreadsheet download. Omit for JSON | ## How a line is priced | | | | - | - | | **Setup** | Charged **once, in full**, in the month the line was ordered. Never prorated — it paid for provisioning work, not for time | | **Monthly** | Prorated: `rate × billable days ÷ days in month` | | **Billing starts** | The day the line is **ordered**, not the day it goes live. The provisioning wait is billable | | **Cancelling** | Billed through the **end of the month** it takes effect, so the final month is always a full month | Rates come from your agency's pricing, the same one the rest of Tuco uses. Each workspace reports the `setupRateCents` and `monthlyRateCents` it was priced at, so a number is always traceable to a rate. ## Example request ```bash theme={null} curl "https://app.tuco.ai/api/agency/statement?month=2026-10" \ -H "Authorization: Bearer tucoagency_xxxxxxxxxxxxx" ``` ## Success response (200) ```json theme={null} { "agencyId": "user_3H08IRicrVUYLDZRyOh4jKRVwrx", "month": "2026-10", "periodStart": "2026-10-01T00:00:00.000Z", "periodEnd": "2026-10-31T23:59:59.999Z", "currency": "usd", "workspaces": [ { "clerkOrgId": "org_3KKJKupHJ8Y9I2NXVAga0c6ZqgT", "name": "Acme Roofing", "plan": "growth", "setupRateCents": 16800, "monthlyRateCents": 14500, "lines": [ { "lineId": "68c1f0a7d2b4e91f3c7a55e2", "identifier": "+14155550134", "channelType": "phone", "orderedAt": "2026-09-10T11:02:00.000Z", "endsAt": null, "status": "active", "billableDays": 31, "daysInMonth": 31, "setupCents": 0, "monthlyCents": 14500, "totalCents": 14500, "fullMonth": true }, { "lineId": "68c1f0a7d2b4e91f3c7a55e9", "identifier": "+14155550198", "channelType": "phone", "orderedAt": "2026-10-20T09:14:00.000Z", "endsAt": null, "status": "provisioning", "billableDays": 12, "daysInMonth": 31, "setupCents": 16800, "monthlyCents": 5613, "totalCents": 22413, "fullMonth": false } ], "setupCents": 16800, "monthlyCents": 20113, "totalCents": 36913 } ], "newLines": 1, "activeLines": 2, "setupCents": 16800, "monthlyCents": 20113, "totalCents": 36913 } ``` Every amount is in **cents**. Each line item is rounded to the nearest cent and the totals are sums of the rounded items, so the rows always add up to the total you print. Reading the second line above: ordered on 20 October, so setup is charged in full and the month is prorated at 12 of 31 days — `14500 × 12 ÷ 31 = 5613`. ## Fields | Field | | | - | - | | `billableDays` / `daysInMonth` | The proration, shown so a client can check it | | `fullMonth` | `true` when the line ran the whole month and `monthlyCents` is the undivided rate | | `orderedAt` | When billing started for this line | | `endsAt` | When it stops, or `null` while it is running | | `newLines` | Lines ordered this month — the ones carrying a setup fee | | `activeLines` | Lines still running at period end | ## CSV ```bash theme={null} curl "https://app.tuco.ai/api/agency/statement?month=2026-10&format=csv" \ -H "Authorization: Bearer tucoagency_xxxxxxxxxxxxx" -o statement.csv ``` One row per line, plus a `TOTAL` row, with dollar amounts rather than cents — ready to paste into whatever you invoice from. ## Error responses | Status | Code | When | | - | - | - | | `400` | `INVALID_MONTH` | `month` is not `YYYY-MM` | | `401` | `UNAUTHORIZED` | Missing, unknown, revoked or expired key | | `403` | `AGENCY_KEY_REQUIRED` | A workspace key (`tuco_…`) was used | | `409` | `NOT_INVOICED` | Your clients are billed through Stripe — their real invoices and your MRR are on the Billing tab | > [!NOTE] > > A Stripe-billed agency gets a `409` on purpose. It already has real Stripe > invoices; a second set of numbers computed a different way would be two > sources of truth that can disagree. ## In the dashboard The same statement is the **Billing** tab in your agency view — month picker, totals, a per-client breakdown you can expand to individual lines, and the same CSV. No API key needed. # Subscribe a Client to a Plan Source: https://docs.tuco.ai/api-reference/endpoint/agency-subscribe POST /api/agency/billing/subscribe Put a client workspace on a Tuco plan, charged off-session to your agency's saved card. One API call, no hosted checkout page, so scripts can run it. > [!NOTE] > > This is **not** a hosted-checkout redirect. The subscription is created directly > against your agency's saved card, so a script can run it. It was the last step of > client onboarding that needed a browser. ## Endpoint * **Method**: `POST` * **Path**: `/api/agency/billing/subscribe` * **Auth**: `Authorization: Bearer tucoagency_xxxxxxxxxxxxx` ([agency key](/api-reference/agency-api-keys)) ## Body | Field | Type | Required | Notes | | - | - | - | - | | `workspaceId` | string | yes | A client workspace in your agency | | `plan` | string | yes | `starter` or `growth`. Mini is retired for agencies | ```bash theme={null} curl https://app.tuco.ai/api/agency/billing/subscribe \ -H "Authorization: Bearer tucoagency_xxxxxxxxxxxxx" \ -H "Content-Type: application/json" \ -d '{"workspaceId":"org_3KKJKupHJ8Y9I2NXVAga0c6ZqgT","plan":"starter"}' ``` ```json theme={null} { "success": true, "subscriptionId": "sub_1QX…", "status": "active", "plan": "starter" } ``` ## You need a card on file first The charge goes to the **agency owner's** saved payment method, off-session. If there isn't one, you get `400 no_card` — add it from Agency view → Billing, then retry. Any agency member (or key) can subscribe a workspace; the charge always lands on the owner's card, so nobody can mis-bill anyone else. The setup fee, if your agency pays one, lands on the subscription's first invoice together with the first month — the same site pricing a direct customer pays, minus whatever discount is attached to your agency. ## If Tuco invoices your agency directly Agencies on **invoice billing** don't need a card at all. The same call puts the client on a plan, creates **no Stripe subscription**, and charges nothing — Tuco bills your agency offline for the whole group. ```json theme={null} { "success": true, "subscriptionId": null, "status": "active", "plan": "growth", "billingMode": "invoice" } ``` `subscriptionId` is `null` and the client workspace gets no `stripeCustomerId`. That absence is the point: **your clients cannot be dunned, emailed about a failed payment, or sent to a checkout page, because they do not exist in Stripe at all.** Add-on lines work the same way — the slot is granted and appears on your agency's next invoice. Invoice billing is set by Tuco on your agency account, not self-serve. Ask us. ## Why the plan is still required either way It's tempting to read "we invoice our own clients" as "no subscription record at all". That breaks the product: a workspace's **plan is what grants its entitlements**. `organizations.plan` sets how many phone and email lines it may hold, and an agency workspace left at `subscriptionStatus: 'none'` is refused outright by the line guard — it cannot order a line, and a transfer into it is rejected with "Target workspace has no active subscription". So subscribe every client, in either mode. A plan is an **entitlement**, not a charge. What you control is the **price**: on Stripe billing that's your agency's discount coupon; on invoice billing it's whatever we agreed. Either way, what you charge your client on your own invoice is separate and Tuco never sees it. ## Error responses | Status | Code | When | | - | - | - | | `400` | `no_card` | No saved payment method on the agency. **Not possible on invoice billing** — no card is needed | | `400` | `already_subscribed` | That workspace already has a subscription | | `400` | — | Missing `workspaceId`/`plan`, or a retired plan | | `401` | `UNAUTHORIZED` | Missing, unknown, revoked or expired key | | `403` | `AGENCY_KEY_REQUIRED` | A workspace key (`tuco_…`) was used | | `403` | — | That workspace is not part of your agency | # Agency Webhooks Source: https://docs.tuco.ai/api-reference/endpoint/agency-webhooks POST /api/agency/webhooks Register a webhook for any client workspace in your Tuco agency — or for every client in one call — without holding each client's API key. > [!NOTE] > > Webhooks stay workspace-scoped: each client gets its own row, its own scope and > its own secret. What changes is **who can create it** — your agency key can, > for any workspace you own, so registration happens in the same script that > creates the client. ## Endpoint * **Method**: `POST` to create, `GET` to read, `DELETE /api/agency/webhooks/{id}` to remove * **Path**: `/api/agency/webhooks` * **Auth**: `Authorization: Bearer tucoagency_xxxxxxxxxxxxx` ([agency key](/api-reference/agency-api-keys)) ## Body | Field | Type | Required | Notes | | - | - | - | - | | `workspaceId` | string | **yes** | A client `clerkOrgId`, or the literal `"all"` for every client in your agency. No default — a typo must not fan out to everyone | | `url` | string | yes | Must parse as a URL | | `events` | string\[] | yes | One or more of the ten events. An unknown event is rejected and named | | `name` | string | yes | Shown in the dashboard | | `description` | string | no | | | `secret` | string | no | Supply your own so **one receiver can verify every client** with a single signing secret. Omit and each client gets its own random one | | `authHeader` | string | no | Sent verbatim as `Authorization` on each delivery — for endpoints that 401 without one | ## One client ```bash theme={null} curl https://app.tuco.ai/api/agency/webhooks \ -H "Authorization: Bearer tucoagency_xxxxxxxxxxxxx" \ -H "Content-Type: application/json" \ -d '{ "workspaceId": "org_3KKJKupHJ8Y9I2NXVAga0c6ZqgT", "url": "https://yourapp.com/hooks/tuco", "events": ["message.reply", "conversation.handover"], "name": "Acme Roofing → our inbox" }' ``` ```json theme={null} { "agencyId": "user_3H08IRicrVUYLDZRyOh4jKRVwrx", "created": 1, "webhooks": [ { "id": "6ac52ed996359b3643c71939", "workspaceId": "org_3KKJKupHJ8Y9I2NXVAga0c6ZqgT", "workspaceName": "Acme Roofing", "secret": "k3K…" } ], "warning": "Save these secrets now. They are not shown again." } ``` ## Every client, one call This is the call that removes "ten clients means ten registrations". Supply your own `secret` and a single receiver can verify all of them. ```bash theme={null} curl https://app.tuco.ai/api/agency/webhooks \ -H "Authorization: Bearer tucoagency_xxxxxxxxxxxxx" \ -H "Content-Type: application/json" \ -d '{ "workspaceId": "all", "url": "https://yourapp.com/hooks/tuco", "events": ["message.reply"], "name": "All clients → our inbox", "secret": "one-secret-i-verify-everything-with" }' ``` Each client still gets its own webhook row, so every delivery carries exactly one tenant's data. Read `workspaceId` off the payload to route it. ## Which clients are not wired up yet ```bash theme={null} curl https://app.tuco.ai/api/agency/webhooks \ -H "Authorization: Bearer tucoagency_xxxxxxxxxxxxx" ``` ```json theme={null} { "agencyId": "user_3H08IRicrVUYLDZRyOh4jKRVwrx", "webhooks": [ { "id": "6ac52ed996359b3643c71939", "workspaceId": "org_3KKJKupHJ8Y9I2NXVAga0c6ZqgT", "workspaceName": "Acme Roofing", "url": "https://yourapp.com/hooks/tuco", "events": ["message.reply"], "name": "Acme Roofing → our inbox", "isActive": true, "failureCount": 0 } ], "workspacesWithoutWebhook": [ { "clerkOrgId": "org_3KKJL4Dnbq…", "name": "Vital Cryotherapy" } ] } ``` `workspacesWithoutWebhook` is the useful read: the clients that would silently receive nothing. Secrets are never returned here — they are shown once, at creation. Add `?workspaceId=org_…` to scope the read to one client. ## Removing one ```bash theme={null} curl -X DELETE https://app.tuco.ai/api/agency/webhooks/6ac52ed996359b3643c71939 \ -H "Authorization: Bearer tucoagency_xxxxxxxxxxxxx" ``` Unlike deleting a line, this **is** available to an API key — a webhook is re-created with one call, so it is not an irreversible action. ## Line-health events Ten events are open to anyone. Two more — `line.down` and `line.recovered` — are not, and they are the ones an agency usually wants most. A line going quiet is operational detail. Sent to the end client it is noise they cannot act on, so Tuco never emails or webhooks it to them. An agency is a different reader: for its clients it **is** the support desk, so these two events are available to agencies Tuco has switched on. > [!NOTE] > > Switched on automatically when your agency is **invoiced** — Tuco bills you, not > your clients, so you are already the operator for every line in the group. On > Stripe billing, ask us and we will enable it by hand without changing how you pay. | Event | Fires when | | - | - | | `line.down` | A line stops sending and the health check confirms it | | `line.recovered` | That same line starts working again | ```bash theme={null} curl https://app.tuco.ai/api/agency/webhooks \ -H "Authorization: Bearer tucoagency_xxxxxxxxxxxxx" \ -H "Content-Type: application/json" \ -d '{ "workspaceId": "all", "url": "https://yourapp.com/hooks/tuco-line-health", "events": ["line.down", "line.recovered"], "name": "Line health → our on-call" }' ``` ### Payload Same envelope as every other event — the line-specific fields sit under `data`. ```json theme={null} { "event": "line.down", "timestamp": "2026-10-07T04:11:52.610Z", "workspaceId": "org_3KKJKupHJ8Y9I2NXVAga0c6ZqgT", "contactOwnerEmail": null, "ghlContactId": null, "ghlLocationId": null, "hsPortalId": null, "hsContactId": null, "data": { "lineId": "68c1f0a7d2b4e91f3c7a55e2", "workspaceId": "org_3KKJKupHJ8Y9I2NXVAga0c6ZqgT", "workspaceName": "Acme Roofing", "agencyId": "user_3H08IRicrVUYLDZRyOh4jKRVwrx", "identifier": "+14155550134", "channelType": "phone", "lineName": "Acme Sales 1", "at": "2026-10-07T04:11:52.610Z" } } ``` The top-level `null`s are the shared CRM fields every event carries; they are not meaningful here. Read `data`. | Field | Notes | | - | - | | `lineId` | The line that went down. Pass it to [`GET /api/lines`](/api-reference/endpoint/get-lines) for its current state | | `workspaceId` / `workspaceName` | Which client. Both are present so one receiver can route across the whole group without a second lookup | | `identifier` | The line's phone or email | | `channelType` | `phone` or `email` | | `lineName` | Display name, or `null` if the line has none | | `at` | When the health check confirmed it (UTC ISO) | The payload carries what an operator can act on and nothing else — no failure strings, no hostnames, no ports. Those stay internal. Signed and retried exactly like every other event — see [Message Webhooks](/api-reference/message-webhooks) for verifying `X-Tuco-Signature`. ### Two ways this is gated Both have to hold: 1. **Agency key only.** A workspace key (`tuco_…`) cannot subscribe to these however the body is crafted — the workspace route never offers them. 2. **Your agency has to be enabled.** If it is not, the create returns `400` with a reason rather than a flat "invalid event", so you can tell a typo from a feature that is simply not on yet: ```json theme={null} { "error": "line.down is only available to agencies Tuco has enabled it for, and only on an agency API key. Ask us to switch it on.", "code": "INVALID_WEBHOOK", "lineHealthEnabled": false } ``` Switching an agency off stops delivery immediately, even though its subscriptions still exist — the check runs at send time, not at subscribe time. ## Relationship to the workspace route [`POST /api/webhooks`](/api-reference/endpoint/create-webhook) still does the same job with that one client's workspace key, and both routes share one validator — a URL or event list rejected by one is rejected by the other, identically. Use the workspace route when your code already holds that client's key; use this one when you are operating across the group. ## Error responses | Status | Code | When | | - | - | - | | `400` | `WORKSPACE_REQUIRED` | `workspaceId` missing. There is deliberately no default | | `400` | `INVALID_WEBHOOK` | Bad URL, empty or unknown `events`, or missing `name`. The body lists `validEvents` | | `400` | `NO_WORKSPACES` | `"all"` with no client workspaces yet | | `400` | `INVALID_ID` | Malformed id on DELETE | | `401` | `UNAUTHORIZED` | Missing, unknown, revoked or expired key | | `403` | `AGENCY_KEY_REQUIRED` | A workspace key (`tuco_…`) was used | | `403` | `NOT_YOUR_WORKSPACE` | `workspaceId` is not in your agency | | `404` | `NOT_FOUND` | The webhook is not one of your agency's | # Re-mint a Client Workspace Key Source: https://docs.tuco.ai/api-reference/endpoint/agency-workspace-keys POST /api/agency/workspace-keys Mint a fresh workspace API key for any client in your agency — for a workspace created before keys were returned, or one whose key was lost or leaked. > [!NOTE] > > [Creating a workspace](/api-reference/endpoint/agency-create-workspace) already > returns its key in the same response, which covers onboarding. This endpoint > covers the two cases that happen afterwards: a client created before that > existed, and a key that was lost or leaked. Without it, both meant signing in as the client and copying a key out of their dashboard by hand — the last manual step in an otherwise scripted onboarding. ## Endpoint * **Method**: `POST` to mint, `GET` to list what a client already has * **Path**: `/api/agency/workspace-keys` * **Auth**: `Authorization: Bearer tucoagency_xxxxxxxxxxxxx` ([agency key](/api-reference/agency-api-keys)) ## Body | Field | Type | Required | Notes | | - | - | - | - | | `workspaceId` | string | **yes** | A client `clerkOrgId`. Must be in your agency | | `name` | string | no | Shown in that client's dashboard. Defaults to `Re-minted by agency`. Truncated at 120 characters | | `revokeExisting` | boolean | no | Default `false`. See below — this is the field that matters | ## Minting ```bash theme={null} curl https://app.tuco.ai/api/agency/workspace-keys \ -H "Authorization: Bearer tucoagency_xxxxxxxxxxxxx" \ -H "Content-Type: application/json" \ -d '{ "workspaceId": "org_3KKJKupHJ8Y9I2NXVAga0c6ZqgT", "name": "Acme Roofing — backend" }' ``` ```json theme={null} { "id": "6ac52ed996359b3643c71939", "workspaceId": "org_3KKJKupHJ8Y9I2NXVAga0c6ZqgT", "key": "tuco_xCsfhTiXXXXXXXXXXXXXXXXXXXXXXXX", "name": "Acme Roofing — backend", "revokedExisting": 0, "warning": "Save this key now. You will not be able to see it again." } ``` `201 Created`. The key is shown **once** — Tuco stores only its hash. It is a normal workspace key: it works on every documented endpoint for that one workspace, and on no other. It is not an agency key and cannot reach any agency endpoint. ## Additive by default Minting does **not** revoke what is already there. The common case is "we lost our copy", and silently killing a live integration to solve that is worse than the problem. So a new key is added alongside the existing ones and nothing breaks. ```bash theme={null} -d '{ "workspaceId": "org_…", "revokeExisting": true }' ``` Pass `revokeExisting: true` for the leaked-key case, where killing it is the point. Every active key on that workspace is deactivated **before** the new one is created, so there is no window in which the leaked key and its replacement are both live. The count comes back as `revokedExisting`. > [!WARNING] > > `revokeExisting: true` breaks any integration still using an old key — the > client's own dashboard key included. Use it when a key has leaked, not as > routine hygiene. ## What a client already has ```bash theme={null} curl "https://app.tuco.ai/api/agency/workspace-keys?workspaceId=org_3KKJKupHJ8Y9I2NXVAga0c6ZqgT" \ -H "Authorization: Bearer tucoagency_xxxxxxxxxxxxx" ``` ```json theme={null} { "agencyId": "user_3H08IRicrVUYLDZRyOh4jKRVwrx", "workspaceId": "org_3KKJKupHJ8Y9I2NXVAga0c6ZqgT", "apiKeys": [ { "id": "6ac52ed996359b3643c71939", "name": "Acme Roofing — backend", "isActive": true, "lastUsedAt": "2026-10-06T19:04:11.882Z", "createdAt": "2026-10-06T18:55:02.117Z" } ] } ``` Secrets are never returned here — only at creation. `lastUsedAt` is the useful read before revoking: a key that has never been used (`null`) is safe to kill. Agency keys are deliberately excluded from this list. It reports workspace keys only. ## Error responses | Status | Code | When | | - | - | - | | `400` | `WORKSPACE_REQUIRED` | `workspaceId` missing. There is no default | | `401` | `UNAUTHORIZED` | Missing, unknown, revoked or expired key | | `403` | `AGENCY_KEY_REQUIRED` | A workspace key (`tuco_…`) was used | | `403` | `NOT_YOUR_WORKSPACE` | That workspace is not part of your agency | Scoped by the same ownership check as every other agency endpoint, so a key can only ever mint into a workspace in its own group. # Analytics Day Conversations Source: https://docs.tuco.ai/api-reference/endpoint/analytics-conversations GET /api/analytics/conversations Every conversation behind one day on the insights chart — all threads with a message that day, newest first, with per-day send and reply counts. > [!NOTE] > > The drill-down for one bar of the [insights](/api-reference/endpoint/analytics-insights) volume chart. Returns every conversation that had at least one message on `date` (cut in the workspace timezone), ordered by most recent activity, with a link straight to the [Unibox](https://app.tuco.ai/unibox) thread. > > Up to 60 conversations are returned; `total` reports how many were active in full. ## Authentication ```bash theme={null} Authorization: Bearer tuco_xxxxxxxxxxxxx ``` ## Query parameters **date** `string` *required* The calendar day to drill into, `YYYY-MM-DD`, cut in the workspace timezone. Returns `400` if missing or malformed. **lineId** `string` Restrict to conversations on a single Tuco line (24-char ObjectId hex). **timezone** `string` IANA zone the day is cut in (e.g. `America/New_York`). Defaults to the workspace timezone. `tz` is accepted as an alias. *** ## Example ```bash Threads active on Aug 15 theme={null} curl "https://app.tuco.ai/api/analytics/conversations?date=2026-08-15" \ -H "Authorization: Bearer tuco_xxxxxxxxxxxxx" ``` ## Success response (200) ```json theme={null} { "success": true, "date": "2026-08-15", "timezone": "America/New_York", "total": 59, "returned": 59, "conversations": [ { "name": "Jasun Liepitz", "phone": "+16185550100", "leadId": "6a82fbf0586005e0ca405c37", "sent": 3, "replied": 2, "lastMessage": "Sounds good, let's set up a time to talk.", "lastDirection": "in", "lastAt": "2026-08-15T18:22:41.000Z", "uniboxHref": "/unibox?conversation=%2B16183034210" } ] } ``` **date** `string` The calendar day the results were cut for, echoed back as `YYYY-MM-DD`. **timezone** `string` IANA zone the day was cut in — the resolved `timezone`/`tz` param, or the workspace default. **total** `number` Distinct conversations active on the day (before the 60-row cap). **returned** `number` How many conversations are in this response (capped at 60). **conversations\[].sent** `number` Outbound messages to this conversation on that day. **conversations\[].replied** `number` Inbound messages from this conversation on that day. **conversations\[].lastDirection** `string` `in` if the day's last message was inbound, `out` if outbound. **conversations\[].uniboxHref** `string` Relative link that opens this thread in Unibox. The conversation id is the E.164 phone. *** ## Error responses | Status | When | | - | - | | `400` | `date` missing or not `YYYY-MM-DD` | | `401` | Missing or invalid API key | | `500` | Server error loading conversations | # Analytics Insights Source: https://docs.tuco.ai/api-reference/endpoint/analytics-insights GET /api/analytics/insights Conversation-shaped analytics for the Tuco AI iMessage API: channel and direction split, a cadence-step funnel with reply attribution, and per-day/hour series. > [!NOTE] > > The companion to [Analytics](/api-reference/analytics). Where that endpoint answers *"how many messages"*, this one answers *"what happened across the conversation"*. > > Every send is classified by its role in the thread — a **net-new** first touch, a cold **follow-up nudge** (the lead hasn't replied yet), or a **response** (you replied to their reply). Each conversation's first reply is credited to the cadence **step** that earned it, and later inbound messages are counted as **reply-to-reply** turns. > > Roles are computed over each conversation's **entire history**, then counted inside your window — so a step-4 send still reads as step 4 even when you only look at a single day. > > Scope is a single workspace (the one behind your key). Agency roll-ups are not offered here yet. ## Authentication ```bash theme={null} Authorization: Bearer tuco_xxxxxxxxxxxxx ``` ## Query parameters **dateFrom** `string` Inclusive start of the window — an ISO 8601 timestamp (`2026-08-01T00:00:00Z`) or a calendar day (`2026-08-01`). Date-only bounds cover whole calendar days in the workspace timezone. Defaults to the trailing 30 days. **dateTo** `string` Inclusive end of the window — ISO timestamp or `YYYY-MM-DD`. **lineId** `string` Restrict to messages sent on a single Tuco line (24-char ObjectId hex). **source** `string` Restrict to one attributed origin (`gohighlevel`, `api`, `dashboard`, `autopilot`, `unattributed`, …). The `sources` breakdown always lists every origin so you can switch. **timezone** `string` IANA zone to cut days and hours in (e.g. `America/New_York`). Defaults to the workspace timezone. `tz` is accepted as an alias. *** ## Example ```bash Last 35 days, one line theme={null} curl "https://app.tuco.ai/api/analytics/insights?dateFrom=2026-07-13&dateTo=2026-08-17&lineId=6a550c00d3c70557446422af" \ -H "Authorization: Bearer tuco_xxxxxxxxxxxxx" ``` ## Success response (200) ```json theme={null} { "success": true, "filter": { "lineId": "6a550c00d3c70557446422af", "source": null, "dateFrom": "2026-07-13T04:00:00.000Z", "dateTo": "2026-08-18T03:59:59.999Z", "timezone": "America/New_York" }, "insights": { "channel": { "attempted": 1986, "imessageDelivered": 948, "smsFallbackSent": 0, "notOnImessage": 1038, "notReached": 1038, "failed": 0, "reached": 948, "imessageReplied": 418, "smsReplied": 0, "totalReplied": 418 }, "unique": { "attempted": 586, "reached": 254, "notOnImessage": 332, "replied": 148 }, "cadence": { "netNew": 329, "nudge": 491, "response": 480, "sentByStep": [329, 154, 137, 85, 115], "firstReplyByStep": [149, 14, 23, 9, 6], "inboundFirst": 4, "firstReplies": 205, "laterReplies": 484, "avgThreadLength": 5.96 }, "engagement": { "delivered": 389, "read": 177, "voiceNotes": 150, "attachments": 150, "scheduled": 84, "failed": 13 }, "conversations": 333, "daily": [{ "day": "2026-07-13", "imessageDelivered": 2, "smsFallbackSent": 0, "notReached": 0, "replied": 2, "activeConversations": 2 }], "hourly": [{ "hour": 0, "sent": 23, "replied": 10 }], "truncated": false }, "sources": [{ "source": "gohighlevel", "sent": 495, "reached": 210 }], "explainer": { "netNew": "First outbound message ever sent to a lead …" } } ``` **insights.channel** `object` Delivery-aware split. `attempted` = all sends; `imessageDelivered` = reached over iMessage; `smsFallbackSent` = fell back **and** an SMS was actually dispatched; `notOnImessage` = recipient has no iMessage (status fallback), a list-quality signal distinct from `failed` (technical); `notReached` = notOnImessage with no SMS dispatched (reached nobody); `reached` = delivered + dispatched SMS. Plus `imessageReplied` / `smsReplied` / `totalReplied`. **insights.unique** `object` Distinct recipients, not message counts: `attempted` = tried, `reached` = a message actually got to, `notOnImessage` = leads never delivered an iMessage (the headline when there is no SMS fallback), `replied` = replied. Reply rate should use `replied / reached` so it's comparable across workspaces regardless of iMessage delivery. **insights.cadence.netNew** `number` First outbound message ever sent to a lead (their first touch). **insights.cadence.nudge** `number` Cold follow-up sends — outbound to a lead who has not replied yet (cadence step 2+). **insights.cadence.response** `number` Outbound sent after the lead had already replied ("I replied to their reply"). **insights.cadence.sentByStep** `number[]` Cold outbound sends by cadence step — index 0..4 = step 1, 2, 3, 4, 5+. **insights.cadence.firstReplyByStep** `number[]` Each conversation's first reply, credited to the step that earned it (same 1..5+ index). **insights.cadence.firstReplies** `number` Conversations that opened — one per lead that replied at least once. **insights.cadence.laterReplies** `number` Reply-to-reply turns — inbound after the conversation had already opened. **insights.cadence.avgThreadLength** `number` Average messages per conversation touched in the window. **insights.conversations** `number` Distinct leads with at least one message in the window. **insights.daily** `object[]` Per-day iMessage delivered / SMS fallback / not-reached / replies, plus that day's distinct `activeConversations` (drives the [day drill-down](/api-reference/endpoint/analytics-conversations)). **insights.hourly** `object[]` Sent and replies by hour of day (0..23) in the workspace timezone. **insights.engagement** `object` Delivery/read receipts, voice notes, attachments, scheduled sends. **insights.truncated** `boolean` `true` when the workspace history was too large to replay for this request; cadence and daily fields are then empty. Narrow the window or filter by line. **sources** `object[]` Where the sending came from. A message carrying a GoHighLevel location counts as GoHighLevel even when sent through the API. Messages with no marker are reported as `unattributed`. *** ## Error responses | Status | When | | - | - | | `401` | Missing or invalid API key | | `500` | Server error computing insights | # Delete Goal Bot Source: https://docs.tuco.ai/api-reference/endpoint/archive-goal-bot DELETE /api/goal-bots/{id} Permanently delete a Tuco goal bot. Conversations it already handled stay untouched. To stop a bot without deleting it, PATCH its status to paused. > [!WARNING] > > **The Try it panel runs against production** (`https://app.tuco.ai`) with the key you paste > into it. There is no sandbox — a request from this page permanently deletes a real bot. > [!NOTE] > > **Goal bots and task agents are the same object.** The two engines merged; `/api/goal-bots` > and `/api/tasks` are aliases over one collection and return identical bodies. Every response > carries both `goalBot` and `taskAgent` (or `goalBots` and `taskAgents`) so integrations written > against either name keep working. > > The older stage-based engine moved to [`/api/instructions`](/api-reference/endpoint/list-instruction-bots) > and is being retired. Deletes the bot permanently. Conversations it already handled are untouched — only the bot is removed. There is no body. > [!WARNING] > > **The built-in Auto Replies bot cannot be deleted.** It is recreated on the next list call, so a > successful delete would be a lie. Deleting it returns `409`; set its `mode` to `manual` to stop it > instead. > [!TIP] > > To stop a bot temporarily, [`PATCH`](/api-reference/endpoint/update-goal-bot) `status` to > `"paused"` rather than deleting it. ## Authentication Pass your workspace API key as a Bearer token, or use a Clerk session token. ```bash theme={null} Authorization: Bearer tuco_xxxxxxxxxxxxx ``` *** ## Path parameter **id** `string` *required* The bot id. A malformed id returns `400 Invalid id`. *** ## Example ```bash theme={null} curl -X DELETE "https://app.tuco.ai/api/goal-bots/6ac3ed5f71adb32c88d566df" \ -H "Authorization: Bearer tuco_xxxxxxxxxxxxx" ``` ### Success (`200 OK`) ```json theme={null} { "success": true } ``` *** ## Errors | Status | When | Body | | - | - | - | | `400` | Malformed `{id}` | `{ "error": "Invalid id" }` | | `400` | Key has no active workspace | `{ "error": "No active workspace" }` | | `401` | Missing or invalid API key | `{ "error": "Unauthorized" }` | | `404` | No bot with that id in your workspace | `{ "error": "Not found" }` | | `409` | Target is the default **Auto Replies** bot | `{ "error": "The Auto Replies bot cannot be deleted. Set its mode to Off (manual) to stop it." }` | # Bulk Add to Do-Not-Contact Source: https://docs.tuco.ai/api-reference/endpoint/bulk-add-dnc PATCH /api/dnc Add up to 10,000 phone numbers and emails to your workspace's Do-Not-Contact list in one idempotent request. Tuco AI iMessage API, bearer-token auth. > [!NOTE] > > Use this to load an existing opt-out list, or to sync opt-outs from your other channels in batches. Contacts already on the list are counted as `skipped`, not errors, so it is safe to resend a whole batch after a timeout. > > Bulk adds do **not** fire the `dnc.added` webhook (you already know about these contacts). For one-at-a-time adds that should notify your webhooks, use [`POST /api/dnc`](/api-reference/endpoint/add-dnc). ## Authentication ```bash theme={null} Authorization: Bearer tuco_xxxxxxxxxxxxx ``` Phones are normalized to E.164 (`(904) 555-1234` → `+19045551234`). Emails are stored lower case. ## Example ```bash theme={null} curl -X PATCH "https://app.tuco.ai/api/dnc" \ -H "Authorization: Bearer tuco_xxxxxxxxxxxxx" \ -H "Content-Type: application/json" \ -d '{ "reason": "whatsapp-opt-out", "entries": [ { "phone": "+15550100001" }, { "phone": "(555) 010-0002" }, { "email": "jane@example.com" } ] }' ``` ## Success response (200) ```json theme={null} { "ok": true, "added": 2, "skipped": 1, "invalid": 0, "failed": 0 } ``` New entries have `source: "api-bulk"` in [`GET /api/dnc`](/api-reference/endpoint/list-dnc). ## Errors | Status | Body | When | | - | - | - | | `207` | `{ "ok": false, …, "failed": n }` | Some entries could not be saved — resend | | `400` | `{ "error": "entries array is required" }` | Missing, empty or non-array `entries` | | `400` | `{ "error": "Maximum 10,000 entries per request" }` | More than 10,000 items | | `401` | `{ "error": "Unauthorized" }` | Missing or invalid API key | | `429` | `{ "error": "Rate limit exceeded" }` | Rate limit exceeded (120/min per workspace) | # Bulk Availability Check Endpoint Source: https://docs.tuco.ai/api-reference/endpoint/bulk-check-availability POST /api/leads/check-availability Bulk-check iMessage availability for many leads or a single address. REST endpoint in the Tuco AI iMessage API — bearer-token auth, JSON request/response, full. ## Endpoint * **Method**: `POST` * **Path**: `/api/leads/check-availability` This endpoint lets you check iMessage availability for multiple leads at once, or for a single arbitrary address, using the same logic Tuco uses internally. *** *** ## Request body Send **exactly one** of `address`, `leadIds` or `listId`. They are checked in that order. **address** `string` A single phone number (E.164) or email to check without creating a lead. Prefer a **phone number** — an email only resolves if it is registered to an Apple account. Must be **non-empty**: `{ "address": "" }` is ignored and the request falls through to the bulk path, which then `404`s if you supplied no `leadIds` or `listId`. **leadIds** `string[]` Lead ids in this workspace to check. Each lead's phone, email and `altPhone1-3` / `altEmail1-3` are tried in order, stopping at the first address that is reachable. **listId** `string` Check every lead in a list instead of naming them. Get a list id from [`GET /api/lists`](/api-reference/endpoint/list-lists). *** ## Check a Single Address (Quick Check) Use this form to check one phone number or email address without creating a lead. > [!WARNING] > > The `address` field must be a **non-empty** string. Sending `{ "address": "" }` will not work -- the empty string is ignored and Tuco falls through to the bulk leads path, which will likely return a `404` if you haven't provided `leadIds` or `listId`. ```json theme={null} { "address": "+12025551234" } ``` **Response** ```json theme={null} { "success": true, "available": true, "address": "+12025551234" } ``` *** ## Bulk Check by Lead IDs Provide a list of lead IDs in the current workspace. Tuco will: * Mark each lead as `availabilityStatus: "available"`, `"unavailable"`, or `"error"`. * Return a summary of how many checks succeeded or failed. ```json theme={null} { "leadIds": [ "667f1f77bcf86cd799439012", "667f1f77bcf86cd799439013", "667f1f77bcf86cd799439014" ] } ``` **Response (synchronous small batch)** ```json theme={null} { "success": true, "checked": 3, "successful": 3, "errors": 0, "results": [ { "leadId": "667f1f77bcf86cd799439012", "available": true, "status": "available" }, { "leadId": "667f1f77bcf86cd799439013", "available": false, "status": "unavailable" } ], "processingMode": "synchronous" } ``` For larger batches, Tuco automatically offloads work to a background job and responds with: ```json theme={null} { "success": true, "message": "Bulk availability check started in background", "jobId": "bulk-availability-2025-10-15T14:30:00.000Z", "checked": 1200, "processingMode": "background" } ``` You can safely trigger this endpoint from your backend and then rely on the updated `availabilityStatus` field on each lead for downstream decisions (for example, whether to message a lead over iMessage or to prefer SMS/email). # Caller ID Details Source: https://docs.tuco.ai/api-reference/endpoint/caller-id-profile GET /api/workspace/caller-id-profile Read, save and submit the business details the Registered caller ID add-on needs. One set per workspace, shared by every line. > [!NOTE] > > The business details carriers need before calls from a [Registered caller ID](/api-reference/endpoint/calling-addons) number can show your business name. > There is **one set per workspace**, used by every line with the add-on. This is the same data as the > **Caller ID details** form in the dashboard. See [Registered caller ID setup](/features/registered-caller-id). > Use a **workspace** API key (`tuco_…`). ## Endpoint * **Method**: `GET` to read, `PUT` to save a draft or submit * **Path**: `/api/workspace/caller-id-profile` * **Auth**: `Authorization: Bearer tuco_xxxxxxxxxxxxx` ## Read — `GET` ```bash theme={null} curl https://app.tuco.ai/api/workspace/caller-id-profile \ -H "Authorization: Bearer tuco_xxxxxxxxxxxxx" ``` ```json theme={null} { "profile": { "displayName": "Acme Debt Relief", "callReasons": ["Sales Call", "Follow-Up Calls"], "logoUrl": null, "legalName": "Acme Holdings, Inc.", "dba": "Acme Debt Relief", "website": "https://acme.com", "ein": "12-3456789", "entityType": "corporation", "stateOfIncorporation": "Florida", "industry": "financial", "employees": "11-50", "address": { "street": "100 Main St", "suite": "", "city": "Miami", "state": "FL", "zip": "33101" }, "billingAddressSame": true, "billingAddress": null, "contact": { "firstName": "Jane", "lastName": "Doe", "title": "Owner", "email": "jane@acme.com", "phone": "+13055550100" }, "billingContactSame": true, "billingContact": null, "callingAreaCode": "305", "certified": true }, "status": "submitted", "submittedAt": "2026-10-31T14:02:11.000Z", "needed": true, "prefilled": false } ``` **profile** `object` The saved details. If nothing is saved yet, an empty profile is returned, pre-filled where we can: company legal name and address from the workspace's newest line order, and the contact's name and email from the user the request is made as (for an API key, the user who created it). `callReasons` starts as `["Sales Call"]`. **status** `string | null` `null` (nothing saved yet), `draft` (saved, not submitted) or `submitted` (sent to us for registration). `PUT` only ever sets `draft` or `submitted`. The dashboard also recognizes `in_review`, `verified` and `rejected`, and treats every value other than `null` and `draft` as submitted. Do the same. **submittedAt** `string | null` When the details were last submitted (ISO 8601), or `null`. **needed** `boolean` `true` when the workspace paid for Registered caller ID at checkout or a line has the add-on. **prefilled** `boolean` `true` when nothing is saved yet and `profile` was pre-filled from a line order or the user. ## Save or submit — `PUT` ```bash theme={null} curl -X PUT https://app.tuco.ai/api/workspace/caller-id-profile \ -H "Authorization: Bearer tuco_xxxxxxxxxxxxx" \ -H "Content-Type: application/json" \ -d '{ "submit": true, "profile": { "displayName": "Acme Debt Relief", "callReasons": ["Sales Call"], "legalName": "Acme Holdings, Inc.", "dba": "Acme Debt Relief", "website": "https://acme.com", "ein": "12-3456789", "entityType": "corporation", "stateOfIncorporation": "Florida", "industry": "financial", "employees": "11-50", "address": { "street": "100 Main St", "city": "Miami", "state": "FL", "zip": "33101" }, "billingAddressSame": true, "contact": { "firstName": "Jane", "lastName": "Doe", "title": "Owner", "email": "jane@acme.com", "phone": "+13055550100" }, "billingContactSame": true, "certified": true } }' ``` | Body field | Type | | | - | - | - | | `profile` | object | **Required.** The details. See the fields below. If it's missing or isn't an object, you get a `400` and nothing is saved. | | `submit` | boolean | `true` submits: every required field must be filled in, and we start registering. Leave it out or send `false` to save a draft. Once the details are submitted, every change must be sent with `submit: true`. A draft save then gets a `409`. | > [!WARNING] > > **`PUT` replaces the whole saved profile.** A field you leave out is saved as empty. To change one > field, `GET` the profile first, change it, and send it all back. ### Profile fields "Submit" means the field is required when `submit` is `true`. Text is trimmed. | Field | Submit | Rules | | - | - | - | | `displayName` | Required | The name shown on calls. Your company or brand, not a person. 1–35 characters, no emoji. | | `callReasons` | Required | 1 to 3 values from the [call reasons list](#call-reasons). Values not on the list are dropped; only the first 3 are kept. | | `logoUrl` | Optional | URL of a square logo image. | | `legalName` | Required | Company legal name. At least 3 characters. | | `dba` | Required | The name customers know you by. | | `website` | Required | For example `https://acme.com` or `acme.com`. | | `ein` | Required | Federal tax ID: 9 digits, `12-3456789` or `123456789`. | | `entityType` | Required | `corporation`, `llc`, `partnership`, `nonprofit` or `other`. | | `stateOfIncorporation` | Required | The state where the company is registered, for example `Florida`. | | `industry` | Required | One value from the [industries list](#industries). | | `employees` | Required | `1-10`, `11-50`, `51-200`, `201-500`, `501-2000`, `2001-10000` or `10001+`. | | `address` | Required | `street`, `city`, `state`, `zip` required. `suite` optional. | | `billingAddressSame` | — | Default `true`. Send `false` with a `billingAddress` (`street`, `city`, `state`, `zip` required). | | `contact` | Required | The main contact, who signs the authorization letter. `firstName`, `lastName`, `title` (job title), `email`, `phone` all required. `email` must be a valid address. `phone` must be a US or Canada number in any common format; it's saved as E.164 (`+13055550100`). | | `billingContactSame` | — | Default `true`. Send `false` with a `billingContact` (`firstName`, `lastName`, `email`, `phone` required, same email and phone rules as `contact`). | | `callingAreaCode` | Optional | 3 digits. The area code you'd like for the separate caller ID numbers. Empty = match each line. | | `certified` | Required (`true`) | Confirms the name and logo accurately represent your business, you own or are allowed to use them, and your calls contain no sex, hate, alcohol, firearms or tobacco content. | **A draft can be half-filled.** It is only rejected for values that are present but wrong: a `displayName` over 35 characters or with emoji, a malformed `ein`, `contact.email` or `website`, an `entityType` / `industry` / `employees` value not on its list, or a `callingAreaCode` that isn't 3 digits. ### Response (`200`) ```json theme={null} { "ok": true, "status": "submitted", "profile": { "displayName": "Acme Debt Relief", "callReasons": ["Sales Call"], "…": "…" }, "submittedAt": "2026-10-31T14:02:11.000Z" } ``` `profile` is what was saved, after trimming and dropping unknown call reasons. To send changes after submitting, `PUT` again with `submit: true`. A later draft save (`submit` left out) sets `status` back to `draft`; `submittedAt` keeps the time of the last submit. ### Rejected (`422`) ```json theme={null} { "error": "Please fill in: Website, Federal tax ID (EIN). Please check: Name shown on calls.", "missing": ["website", "ein"], "invalid": ["displayName"] } ``` `missing` and `invalid` hold field paths such as `contact.title` or `billingAddress.zip`. Nothing is saved when the request is rejected. ## Error responses | Status | When | | - | - | | `400` | The body isn't valid JSON, or `profile` is missing or isn't an object. Nothing is saved | | `401` | Missing or invalid key | | `403` | An agency key (`tucoagency_…`) was used. This is a per-workspace setting | | `404` | Workspace not found | | `409` | The details are already submitted and you sent a draft (`submit` not `true`). Send the change with `submit: true`. Nothing is saved | | `422` | A required field is missing (on submit) or a value is invalid. See above | ## What happens after you submit We register your business with the carriers, which usually takes a few business days. The main contact signs one short authorization letter. Once a line's Registered caller ID is live, its [calling add-ons](/api-reference/endpoint/calling-addons) show `status: "active"` and the `callingNumber` its calls go out from. ## Call reasons `Sales Call`, `Follow-Up Calls`, `Returning Your Call`, `Responding to Your Inquiry`, `Customer Service`, `Account Services`, `Your Account`, `Account Notification`, `Account Alert`, `Agent Call Back`, `Appointment Confirmation`, `Appointment Reminder`, `Confirm Appointment`, `Reschedule Request`, `Response Requested`, `General Support`, `Technical Support`, `Policy Update`, `Accounting Department`, `Confirm Status`, `Identity Verification`, `Fraud Alert`, `Confirm Card Use`, `Confirm Order`, `Order Confirmation`, `Your Order`, `Confirm Receipt`, `Delivery ETA`, `Today's Delivery`, `Upcoming Delivery`, `Item Ready`, `Order Ready`, `Reservation Ready`, `Rx Ready`, `Recall`, `Service Outage Notification`, `Verification Code`, `Investor Relations`, `Flight Arrival`, `Flight Boarding`, `Flight Cancellation`, `Flight Delay`, `School Closing Alert`, `Snow Alert`, `Weather Alert` Values are case-sensitive. ## Industries `financial`, `finance`, `banking`, `collections`, `accounting`, `billing`, `insurance`, `legal`, `law`, `real estate`, `property`, `sales`, `marketing`, `business`, `customer service`, `support`, `software`, `technology`, `tech`, `telecom`, `communications`, `healthcare`, `health`, `medical`, `pharmacy`, `education`, `retail`, `ecommerce`, `delivery`, `shipping`, `logistics`, `travel`, `hospitality`, `hotel`, `media`, `surveys`, `market research`, `notifications`, `scheduling`, `government`, `public`, `charity`, `nonprofit` # Calling Add-on Slots Source: https://docs.tuco.ai/api-reference/endpoint/calling-addon-slots GET /api/lines/calling-addon-slots How many calling add-ons your workspace pays for, how many lines use them, and how many are free for the next phone line at no new charge. > [!NOTE] > > Read-only. Use a **workspace** API key (`tuco_…`). Each calling add-on your workspace pays for is a **slot**. Add-ons ticked at checkout buy one slot for every phone line in your plan. Each phone line ordered after that takes one free slot of each add-on automatically, with no new charge. This endpoint shows what's left. ```bash theme={null} curl https://app.tuco.ai/api/lines/calling-addon-slots \ -H "Authorization: Bearer tuco_xxxxxxxxxxxxx" ``` ```json theme={null} { "slots": { "facetime_audio": { "paid": 2, "held": 1, "free": 1 }, "caller_id_registration": { "paid": 0, "held": 0, "free": 0 } } } ``` One entry per add-on key (`facetime_audio`, `caller_id_registration`): **paid** `number` Slots of this add-on on the workspace's subscription. **held** `number` Lines that have this add-on (awaiting payment, setting up, or active). **free** `number` `paid` minus `held`, never below 0. More than 0 means the next phone line gets this add-on automatically with no new charge, and adding it to an existing line with [`POST /api/lines/{id}/calling-addons`](/api-reference/endpoint/calling-addons) costs nothing. A workspace without a subscription (for example, an agency workspace billed by invoice) returns `0` for everything. The same number is on each add-on in [`GET /api/lines/{id}/calling-addons`](/api-reference/endpoint/calling-addons) as `prepaidFree`. ## Error responses | Status | When | | - | - | | `401` | Missing or invalid key | | `403` | An agency key (`tucoagency_…`) was used | | `502` | `"Could not read add-on slots."` Billing couldn't be read. Try again | # Calling Add-ons Source: https://docs.tuco.ai/api-reference/endpoint/calling-addons GET /api/lines/{id}/calling-addons List and buy per-line calling add-ons — the FaceTime Audio add-on and the Registered caller ID add-on — for a phone line in your workspace. > [!WARNING] > > **The Try it panel runs against production** with the key you paste. `POST` charges your card, unless it uses an add-on you already paid for at checkout. Every phone line includes calling: **500 outgoing minutes per line per month** (pooled across your phone lines) with **call recording**, **unlimited incoming calls** forwarded to one number in the same country as the eSIM, and extra minutes at **\$3 per 100**. Regular calls go out through Telnyx using your line's number. The person you call may see **"Potential spam"** unless they saved your number or tapped "Mark as known" — text them first. Carriers grade each call with a STIR/SHAKEN attestation, and because Telnyx can't own the number your line uses for iMessage, calls are attested **B** rather than **A**. This is industry-wide: every iMessage provider, Sendblue included, calls from an iMessage number with B — an **A** needs a carrier-owned number, and those can only do SMS, not iMessage. Two add-ons avoid that: | `addon` | Price | What it does | | - | - | - | | `facetime_audio` | \$100/mo per line | Calls go over FaceTime Audio — no carrier spam label. Costs more because it needs different hardware than iMessage. | | `caller_id_registration` | $50 setup + $50/mo per line + \$0.075 per call | A separate, fully-attested calling number registered with carriers (Branded Calling) that shows your business name on US-to-US calls to T-Mobile and Verizon mobiles. Calls come from that number, not your iMessage number. Carrier vetting can take a few business days. Needs your [business details](/api-reference/endpoint/caller-id-profile) before it can go live. | **Add-ons bought at checkout are already paid for.** Checkout buys one per phone line in your plan. Each phone line ordered after that gets one automatically, and adding one to an existing line uses it first, with no new charge. See how many are left with [Calling Add-on Slots](/api-reference/endpoint/calling-addon-slots), or in `prepaidFree` below. ## List — `GET /api/lines/{id}/calling-addons` **id** `string` *required* The line's `_id`. ```json theme={null} { "lineId": "6a091e74542d9e3d645925ae", "recordingDisclosure": { "enabled": false, "message": null, "defaultMessage": "This call may be recorded for quality and training purposes.", "maxLength": 300 }, "included": ["500 outgoing minutes per line per month, with call recording.", "…"], "addons": [ { "key": "facetime_audio", "label": "FaceTime Audio add-on", "beta": false, "price": "$100/mo per line", "monthlyCents": 10000, "setupCents": 0, "perCallCents": 0, "status": "none", "prepaidFree": 1, "paymentUrl": null }, { "key": "caller_id_registration", "label": "Registered caller ID add-on", "beta": false, "price": "$50 setup + $50/mo + $0.075/call per line", "monthlyCents": 5000, "setupCents": 5000, "perCallCents": 7.5, "status": "active", "prepaidFree": 0, "paymentUrl": null, "callingNumber": "+12125550199" } ] } ``` `status` is one of `none`, `awaiting_payment` (pay `paymentUrl`), `pending_setup` (paid — we're setting it up), `active`, or `canceled`. `prepaidFree` is how many of this add-on the workspace already paid for (at checkout) that no line uses yet. More than `0` means adding it to this line costs nothing today. It is `0` if billing can't be read at that moment. Each add-on also carries `points`, the plain-English description shown in the dashboard. The response also has `potentialSpam`, the dashboard's explanation of the "Potential spam" label. `recordingDisclosure` is the line's free **call recording notice** setting (`message: null` = the default text). Turn it on or change the text with [Update a Line](/api-reference/endpoint/update-line#call-recording-notice). It isn't an add-on and costs nothing. It doesn't play on FaceTime Audio calls. ## Add to a line — `POST /api/lines/{id}/calling-addons` There are two ways to add an add-on to a line. **Use one you already paid for at checkout.** No charge, no consent needed: ```bash theme={null} curl -X POST "https://app.tuco.ai/api/lines/6a091e74542d9e3d645925ae/calling-addons" \ -H "Authorization: Bearer tuco_xxxxxxxxxxxxx" \ -H "Content-Type: application/json" \ -d '{ "addon": "caller_id_registration", "usePrepaidSlot": true }' ``` **Buy a new one.** Charged to the card on file now: ```bash theme={null} curl -X POST "https://app.tuco.ai/api/lines/6a091e74542d9e3d645925ae/calling-addons" \ -H "Authorization: Bearer tuco_xxxxxxxxxxxxx" \ -H "Content-Type: application/json" \ -d '{ "addon": "facetime_audio", "acceptCharges": true }' ``` * `addon` — `facetime_audio` or `caller_id_registration`. * `usePrepaidSlot` — `true` to use an add-on already paid for at checkout. **Never charges.** If none is left (`prepaidFree` is `0`), it returns `409` with `"code": "PREPAID_SLOT_TAKEN"` and nothing is charged. * `acceptCharges` — must be `true` to buy a new one: you agree to the setup fee plus today's prorated share of the monthly, then monthly. Non-refundable. Without it, and with no add-on already paid for: `422`. **An add-on you already paid for is always used first.** While `prepaidFree` is more than `0`, any `POST` for that add-on uses it and charges nothing, even if you sent `acceptCharges: true`. If another order took the last one a moment earlier, a request with `acceptCharges: true` (and no `usePrepaidSlot`) goes on to buy a new one. Any other request gets `409 PREPAID_SLOT_TAKEN` and is not charged. ```json theme={null} { "addon": "caller_id_registration", "ok": true, "status": "pending_setup", "billingMode": "stripe", "chargedCents": 0, "usedPrepaidSlot": true } ``` `chargedCents` is what this request charged (`0` when a paid-for add-on was used), and `usedPrepaidSlot` is `true` when it used one. A new purchase charges the card on file immediately. It returns `201` with `status: "pending_setup"` once paid, or `202` with `status: "awaiting_payment"` and a `paymentUrl` only when the card is declined or the bank requires authentication (3-D Secure) — the customer confirms there, and the add-on starts once paid. An unpaid `paymentUrl` lapses after about 23 hours; the add-on then goes back to `none` and can be bought again. Registered caller ID calls are billed at \$0.075 each, added to your next invoice. Registered caller ID can't go live until the workspace's [caller ID details](/api-reference/endpoint/caller-id-profile) are submitted. ### Errors Errors return `{ "error": "…", "code": "…" }`. | Status | `code` | When | | - | - | - | | `400` | — | `addon` isn't `facetime_audio` or `caller_id_registration` | | `400` | `NOT_A_PHONE_LINE` | The line is an email line | | `402` | `NO_BILLING_ACCOUNT` | The workspace has no active billing account | | `404` | `LINE_NOT_FOUND` | No such line in this workspace | | `409` | `ALREADY_ACTIVE` | The line already has this add-on | | `409` | `PAYMENT_IN_PROGRESS` | This add-on, or another add-on payment on the workspace, is still waiting on payment. Pay or let it lapse first | | `409` | `PREPAID_SLOT_TAKEN` | `usePrepaidSlot` was sent (or the last paid-for add-on was just used) and none is left. Nothing was charged | | `422` | — | `acceptCharges` isn't `true` and there's no add-on already paid for | | `500` | — | Your agreement to the charge couldn't be recorded. Nothing was charged. Try again | | `502` | — | Billing failed. The add-on was not added | ## Removing an add-on > [!WARNING] > > **Add-ons can't be removed after purchase.** Contact [support@tuco.ai](mailto:support@tuco.ai) to change them. > `DELETE /api/lines/{id}/calling-addons` returns `403` with `"code": "ADDON_REMOVAL_SUPPORT_ONLY"`. ## Ordering add-ons with a new line Send `callingAddons` and `acceptCallingAddonCharges: true` on [Create Line Request](/api-reference/endpoint/create-line-request). Add-ons bought with your plan at checkout attach to new phone lines automatically, with no second charge, so leave those out of `callingAddons`. [Calling Add-on Slots](/api-reference/endpoint/calling-addon-slots) shows how many are left. # Cancel Pending Messages Source: https://docs.tuco.ai/api-reference/endpoint/cancel-for-lead POST /api/messages/cancel-for-lead Cancel all pending, scheduled, and queued Tuco AI messages for a lead — use when a lead replies Stop or opts out to instantly halt outbound sends. > [!WARNING] > > **The Try it panel runs against production** (`https://app.tuco.ai`) with the key you paste > into it. There is no sandbox — a request from this page cancels real queued messages. > [!NOTE] > > Call this endpoint when a lead replies "Stop", "Unsubscribe", or any opt-out keyword. It cancels **all** pending, scheduled, and queued messages for that lead and removes their jobs from the processing queue. ## Authentication ```bash theme={null} Authorization: Bearer tuco_xxxxxxxxxxxxx ``` ## Request body You must provide **at least one** of these identifiers: **leadId** `string` Cancel all pending messages for this lead ID. Most direct — skips the lookup step. **recipientPhone** `string` Phone number (E.164 format). Tuco looks up the lead by phone (including altPhone1-3), then cancels all pending messages for that lead. If no lead is found, cancels messages matching this phone directly. **recipientEmail** `string` Email address. Tuco looks up the lead by email (including altEmail1-3), then cancels all pending messages for that lead. If no lead is found, cancels messages matching this email directly. *** ## How it works **1. Identify the lead** If `leadId` is provided, use it directly. Otherwise, look up the lead by `recipientPhone` or `recipientEmail` (checks primary + alt fields). **2. Find cancellable messages** Query all messages for this lead (or address) with status `queued`, `pending`, or `scheduled`. **3. Cancel in database** Bulk update all matching messages to `status: "cancelled"`. **4. Remove from queue** Remove each message's BullMQ processing job so it won't be picked up by the worker. *** ## Examples ```bash Cancel by phone theme={null} curl -X POST "https://app.tuco.ai/api/messages/cancel-for-lead" \ -H "Authorization: Bearer tuco_xxxxxxxxxxxxx" \ -H "Content-Type: application/json" \ -d '{ "recipientPhone": "+14425550100" }' ``` ```bash Cancel by email theme={null} curl -X POST "https://app.tuco.ai/api/messages/cancel-for-lead" \ -H "Authorization: Bearer tuco_xxxxxxxxxxxxx" \ -H "Content-Type: application/json" \ -d '{ "recipientEmail": "john@example.com" }' ``` ```bash Cancel by lead ID theme={null} curl -X POST "https://app.tuco.ai/api/messages/cancel-for-lead" \ -H "Authorization: Bearer tuco_xxxxxxxxxxxxx" \ -H "Content-Type: application/json" \ -d '{ "leadId": "69b2c41d352a78479d2c623b" }' ``` *** ## Success response (200) ```json theme={null} { "success": true, "cancelledCount": 3, "jobsRemovedFromQueue": 2, "leadId": "69b2c41d352a78479d2c623b", "messageIds": [ "69dba0001111111111111111", "69dba0001111111111111112", "69dba0001111111111111113" ] } ``` **success** `boolean` Always `true` on success (even when 0 messages cancelled). **cancelledCount** `integer` Number of messages set to `cancelled` in the database. **jobsRemovedFromQueue** `integer` Number of BullMQ jobs removed. May be less than `cancelledCount` if some jobs already started processing. **leadId** `string` The resolved lead ID (may be `null` if no lead was found and cancellation was done by address). **messageIds** `string[]` IDs of all cancelled messages. ## Error responses | Status | When | Body | | - | - | - | | `400` | No identifier provided | `{ "error": "Either leadId, recipientPhone, or recipientEmail is required" }` | | `400` | Invalid `leadId` format | `{ "error": "Invalid leadId" }` | | `401` | Missing or invalid API key | `{ "error": "Unauthorized" }` | | `500` | Server error | `{ "error": "Internal server error" }` | *** ## Usage with n8n / automation Wire this into your reply handler workflow. When a lead replies with an opt-out keyword, call this endpoint with their phone number to stop all future sequence messages: ```json theme={null} { "method": "POST", "url": "https://app.tuco.ai/api/messages/cancel-for-lead", "headers": { "Authorization": "Bearer tuco_xxxxxxxxxxxxx" }, "body": { "recipientPhone": "{{ $json.phone }}" } } ``` # Cancel a Line Source: https://docs.tuco.ai/api-reference/endpoint/cancel-line POST /api/lines/cancel Request a line cancellation. The line keeps sending until the end of the period you have paid for, then stops. Nothing is deleted. > [!NOTE] > > This is a **cancellation request**, shaped like cancelling a subscription — not > a delete. The line keeps working right up to the end of the period you have > already paid for. Nothing is removed, and the conversations on it stay readable > afterwards. ## Endpoint * **Method**: `POST` * **Path**: `/api/lines/cancel` * **Auth**: `Authorization: Bearer tuco_xxxxxxxxxxxxx` ([workspace key](/api-reference/api-keys)) ## Body | Field | Type | Required | Notes | | - | - | - | - | | `lineId` | string | **yes** | The line to cancel. 24-character hex id, from [`GET /api/lines`](/api-reference/endpoint/get-lines) | ## Example request ```bash theme={null} curl https://app.tuco.ai/api/lines/cancel \ -H "Authorization: Bearer tuco_xxxxxxxxxxxxx" \ -H "Content-Type: application/json" \ -d '{ "lineId": "6ac583d23e36ad490e7a902b" }' ``` ## Success response (200) ```json theme={null} { "success": true, "lineId": "6ac583d23e36ad490e7a902b", "status": "cancellation_requested", "newlyRequested": true, "cancelEffectiveAt": "2026-10-31T23:59:59.999Z", "cancelBasis": "calendar_month_end", "setupFeeRefunded": false, "message": "Cancellation requested. This line keeps sending until 2026-10-31T23:59:59.999Z, then stops. The setup fee is not refunded." } ``` ## The line keeps sending This is the part worth internalising: **a cancelled line is still a working line** until `cancelEffectiveAt`. It sends, it receives, it appears in your workspace. You paid for the period; you keep it. What changes immediately is only what the line is *called*. [`GET /api/lines`](/api-reference/endpoint/get-lines) reports: | `status` | Meaning | | - | - | | `active` | Normal | | `cancellation_requested` | Cancelled, **still sending**, stops at `cancelEffectiveAt` | | `canceled` | The date has passed. No longer sends | Each line also carries `cancelEffectiveAt`, or `null` if it is not cancelling. ## When it stops | `cancelBasis` | | | - | - | | `subscription_period_end` | The end of your current Stripe billing period | | `calendar_month_end` | The last moment of the current UTC month — used when Tuco invoices your agency and there is no Stripe period to read | > [!WARNING] > > **The setup fee is not refunded.** It paid for provisioning that has already > happened — a number acquired, a device configured. `setupFeeRefunded: false` is > returned on every response rather than left unsaid. ## Calling it twice is safe A second request returns the **same** date with `newlyRequested: false`. The date is set once and never recomputed, so a repeated call can never accidentally move your cancellation into the following month. ```json theme={null} { "success": true, "status": "cancellation_requested", "newlyRequested": false, "cancelEffectiveAt": "2026-10-31T23:59:59.999Z", "message": "This line was already scheduled to stop at 2026-10-31T23:59:59.999Z." } ``` ## Only an active line A line that is still being provisioned has never sent anything, so there is no paid period to run out. Cancel that order instead — the error says so: ```json theme={null} { "error": "Only an active line can be cancelled at period end. A line still being provisioned is cancelled through POST /api/line-requests/{id} with action \"cancel\".", "code": "LINE_NOT_ACTIVE", "status": "provisioning" } ``` ## Error responses | Status | Code | When | | - | - | - | | `400` | `LINE_REQUIRED` | `lineId` missing | | `400` | `LINE_NOT_ACTIVE` | The line is not active — see above | | `401` | `UNAUTHORIZED` | Missing, unknown, revoked or expired key | | `403` | `NO_SUBSCRIPTION` | The workspace has no active plan | | `403` | `AGENCY_ONLY` | An agency-owned workspace: only the agency can cancel its lines | | `404` | `LINE_NOT_FOUND` | No such line in this workspace | ## If your workspace belongs to an agency Lines in an agency-managed workspace are paid for by the agency, so only the agency can end one. You can still read their status and [order new ones](/api-reference/endpoint/create-line-request) — ask your agency admin to cancel. # Check iMessage Availability (Single Address) Source: https://docs.tuco.ai/api-reference/endpoint/check-availability GET /api/check-availability Check if a phone number or email is on iMessage -- no saved lead required. REST endpoint in the Tuco AI iMessage API — bearer-token auth, JSON. The simplest way to check if a phone or email has iMessage. Just pass the address as a query parameter. No lead ID, no saved contact required. > [!TIP] > > **Don't know which endpoint to use?** Start here. This is the one you want for a quick, one-off check. > > | I have... | Use this | > | - | - | > | A phone number or email | **This endpoint** (`GET /api/check-availability?address=...`) | > | Multiple phones/emails to check at once | [`POST /api/check-availability`](#batch-check-multiple-addresses) (see below) | > | A saved lead ID | [`GET /api/leads/check-availability`](/api-reference/endpoint/lead-check-availability) | > | Multiple lead IDs or a list | [`POST /api/leads/check-availability`](/api-reference/endpoint/bulk-check-availability) | > | A phone + email and want round-robin | [`POST /api/check-availability-rr`](/api-reference/endpoint/check-availability-rr) | *** ## Single Address Check ### Request ```bash theme={null} curl "https://app.tuco.ai/api/check-availability?address=%2B14155551234" \ -H "Authorization: Bearer tuco_YOUR_KEY" ``` **address** `string` *required* **The phone number to check, in E.164 format** — e.g. `+14155551234`. URL-encode the `+` as `%2B`. An email address is also accepted, but it only tells you whether that address is registered to an Apple account. For "can I iMessage this person", check their **phone number**. ### Response ```json theme={null} { "success": true, "available": true, "address": "+14155551234" } ``` **success** `boolean` Whether the API call completed without errors. **available** `boolean` `true` if the address is registered on iMessage right now. **address** `string` The address that was checked (echoed back). ### Not available ```json theme={null} { "success": true, "available": false, "address": "+14155551234" } ``` *** ## Single Address Check (POST) **`POST /api/check-availability`** You can also POST a single address instead of using the GET query param. ### Request ```bash theme={null} curl -X POST https://app.tuco.ai/api/check-availability \ -H "Authorization: Bearer tuco_YOUR_KEY" \ -H "Content-Type: application/json" \ -d '{ "address": "+14155551234" }' ``` **address** `string` A single phone number or email to check. Mutually exclusive with `addresses`. ### Response ```json theme={null} { "success": true, "results": [ { "address": "+14155551234", "available": true } ] } ``` *** ## Batch Check (Multiple Addresses) **`POST /api/check-availability`** Check up to 100 addresses in a single request. Each address is checked sequentially (3s gap per device). ### Request ```bash theme={null} curl -X POST https://app.tuco.ai/api/check-availability \ -H "Authorization: Bearer tuco_YOUR_KEY" \ -H "Content-Type: application/json" \ -d '{ "addresses": ["+14155551234", "+14155559999", "frank@example.com"] }' ``` **addresses** `string[]` Array of phone numbers or emails to check. Max 100 per request. Mutually exclusive with `address`. ### Response ```json theme={null} { "success": true, "results": [ { "address": "+14155551234", "available": true }, { "address": "+14155559999", "available": false }, { "address": "frank@example.com", "available": false } ] } ``` *** ## Rate Limits | Limit | Value | | - | - | | API rate limit | **200 req/min** per workspace | | Daily cap | **70 checks/day per line** (e.g., 3 lines = 210 checks) | | Device gap | **3 seconds** between checks on the same physical device | *** ## Error Codes | Code | When | Body | | - | - | - | | `400` | Missing or empty `address` param (GET) | `{ "error": "Address parameter is required (phone or email)" }` | | `400` | Missing both `address` and `addresses` (POST) | `{ "error": "addresses array is required and must not be empty" }` | | `400` | Too many addresses (POST, >100) | `{ "error": "Maximum 100 addresses per request" }` | | `401` | Invalid API key | `{ "error": "Unauthorized" }` | | `429` | Rate limit exceeded | `{ "error": "Rate limit exceeded" }` | | `429` | All lines hit daily cap | `{ "error": "Daily availability check quota exhausted" }` | | `500` | Server error | `{ "error": "Internal server error" }` | # Check iMessage Availability (Round-Robin) Source: https://docs.tuco.ai/api-reference/endpoint/check-availability-rr POST /api/check-availability-rr Check if a phone or email has iMessage, using round-robin across your lines. REST endpoint in the Tuco AI iMessage API — bearer-token auth, JSON. ## Overview Round-robin iMessage availability check across your workspace's eligible lines. Returns whether any of the provided phone numbers or emails are registered on iMessage. > [!WARNING] > > **70 checks/day per line (hard cap).** Each line can perform up to 70 availability > checks per day. With 3 lines you get 210 total. When all lines are exhausted, > you receive a `429` with `Retry-After: 3600`. > > **Recommended:** Skip this endpoint entirely. Instead, call `POST /api/messages` > directly and listen for the `message.fallback` webhook to trigger your SMS/WhatsApp > fallback. This avoids burning your daily availability quota. See > [Integration Patterns](#recommended-pattern-send--fallback-webhook) below. *** ## Request **phones** `string[]` Array of phone numbers to check (checked first, in order). **emails** `string[]` Array of email addresses to check (checked after phones). ```bash theme={null} curl -X POST https://app.tuco.ai/api/check-availability-rr \ -H "Authorization: Bearer tuco_YOUR_KEY" \ -H "Content-Type: application/json" \ -d '{ "phones": ["+14155551234"], "emails": ["frank@example.com"] }' ``` *** ## Response ### Available ```json theme={null} { "available": true } ``` ### Not Available ```json theme={null} { "available": false, "reason": "Contact not available on iMessage" } ``` ### Quota Exhausted (429) ```json theme={null} { "available": false, "reason": "Daily availability check quota exhausted" } ``` *** ## Rate Limits | Limit | Value | | - | - | | API rate limit | **200 req/min** per workspace | | Daily cap | **70 checks/day per line** | | Device gap | **3 seconds** between checks on the same physical device | > [!NOTE] > > Availability checks do **not** consume your daily send quota. Send limits and > availability limits are tracked separately in Redis. *** ## Recommended Pattern: Send + Fallback Webhook Instead of checking availability first, just send via `POST /api/messages` and handle the `message.fallback` webhook to trigger your SMS or WhatsApp fallback. **Why this is better:** * No availability quota consumed (saves your 70/day/line cap) * One API call instead of two * Webhook-driven fallback is reliable and async * Works even when availability quota is exhausted ```python theme={null} # Step 1: Just send. Don't check availability first. resp = requests.post("https://app.tuco.ai/api/messages", headers=headers, json={ "message": "Hey, quick question about your demo.", "recipientPhone": "+14155551234", "recipientName": "Frank" }) # Step 2: Handle webhooks on your server @app.post("/tuco-webhook") def handle(request): event = request.json["event"] if event == "message.sent": pass # iMessage delivered elif event == "message.fallback": # No iMessage — trigger WhatsApp/SMS fallback phone = request.json["message"]["recipientPhone"] send_whatsapp(phone) elif event == "message.reply": reply_text = request.json["message"] # string notify_team(request.json["leadId"], reply_text) return {"ok": True} ``` *** ## Error Codes | Code | When | Body | | - | - | - | | 400 | No phones or emails provided | `{ "available": false, "reason": "No phone or email addresses provided" }` | | 401 | Bad API key | `{ "error": "Unauthorized" }` | | 429 | API rate limit hit | `{ "error": "Rate limit exceeded" }` | | 429 | Daily cap exhausted | `{ "available": false, "reason": "Daily availability check quota exhausted" }` | | 500 | Server error | `{ "error": "Internal server error" }` | # List Conversations Source: https://docs.tuco.ai/api-reference/endpoint/conversations GET /api/unibox/conversations Read a workspace's inbox — every conversation with its thread, unread count, tags and status, with filters and pagination. > [!NOTE] > > This is the inbox behind the Tuco unibox. One call gives you the conversation > list with each thread's messages, so you can build your own inbox UI. ## Endpoint * **Method**: `GET` * **Path**: `/api/unibox/conversations` * **Auth**: `Authorization: Bearer tuco_xxxxxxxxxxxxx` (workspace key) ## Two things that surprise people **A conversation is keyed by recipient, not by lead.** There is no `leadId` on a conversation — it is identified by the phone number or email address at `recipient`. That is also why the deep link is `?conversation=
`. **The thread holds what actually went out or came in.** Messages still `queued`, `pending` or `scheduled` are deliberately **not** in it — a conversation shows history, not intent. Read the outbound queue from [`/api/unibox/scheduled`](#the-pending-queue) instead. If you expect "everything for this contact" here, you will wrongly conclude the follow-ups were lost. ## Pagination | Param | Default | Notes | | - | - | - | | `limit` | `50` | **Capped at 100.** A larger value is silently reduced — read `pagination.limit` back | | `page` | `1` | Offset paging | | `cursor` | — | Opaque cursor from `pagination.nextCursor`. Preferred for deep paging | | `messageLimit` | unlimited | Cap the messages carried per conversation. Use a small N for a list view, then re-fetch one thread with `?conversation=` | ```json theme={null} "pagination": { "page": 1, "limit": 50, "totalCount": 128, "totalPages": 3, "nextCursor": "eyJsYXN0TWVzc2FnZUF0IjoiMjAyNi0xMC0wN1QxODoy…", "hasMore": true } ``` ## Filters All are query params and all intersect. | Param | Matches | | - | - | | `tag` | Conversations whose lead carries this tag | | `status` | Conversation state, e.g. `unread` | | `line` | Only conversations on this sending line (`lineId`) | | `conversation` | One thread, by recipient address. URL-encode a `+` as `%2B` | | `contactOwner` | The workspace member who owns the contact | | `propertyKey` + `propertyOp` + `propertyValue` | A custom-property comparison. `propertyStandard=true` targets a standard field | ```bash theme={null} curl "https://app.tuco.ai/api/unibox/conversations?limit=25&tag=vip&status=unread" \ -H "Authorization: Bearer tuco_xxxxxxxxxxxxx" ``` ## Response ```json theme={null} { "conversations": [ { "id": "…", "recipient": "+15558880001", "recipientName": "Dana Reyes", "recipientType": "phone", "lastMessageAt": "2026-10-07T18:22:05.117Z", "unreadCount": 1, "status": "unread", "tags": [], "leadTags": ["vip"], "messages": [ { "status": "sent", "direction": "outbound", "body": "Hi Dana" }, { "status": "delivered", "direction": "inbound", "body": "Tell me more" } ] } ], "pagination": { "page": 1, "limit": 25, "totalCount": 1, "totalPages": 1, "nextCursor": null, "hasMore": false } } ``` ## Group chats A group chat your line is in is its own conversation: * `id` starts with `group:` (for example `group:iMessage;+;chat606535035660201399`) * `isGroup` is `true` * `groupMembers` lists each member's `address` and `name` * each received message has `groupSenderAddress` (the member who sent it) * there is no lead To read one group, URL-encode its id in `?conversation=`. An unencoded `+` turns into a space and the group is silently not found. ```bash theme={null} curl -G "https://app.tuco.ai/api/unibox/conversations" \ -H "Authorization: Bearer tuco_xxxxxxxxxxxxx" \ --data-urlencode "conversation=group:iMessage;+;chat606535035660201399" ``` If the group is not on the page you asked for, it comes back as `preselectedConversation`. Reply with [Send to a Group Chat](/api-reference/endpoint/send-group-message). ## The pending queue Anything not yet sent: ```bash theme={null} curl https://app.tuco.ai/api/unibox/scheduled \ -H "Authorization: Bearer tuco_xxxxxxxxxxxxx" ``` To stop it going out, see [Cancel Pending Messages](/api-reference/endpoint/cancel-for-lead). ## Related * `GET /api/unibox/tags` — the tags you can filter on * `GET /api/unibox/custom-properties` — the property keys for `propertyKey` * `GET /api/replies` — a flat, paginated feed of inbound replies * `POST /api/unibox/mark-read`, `/archive`, `/flag`, `/send-reply` — act on a conversation > [!WARNING] > > `GET /api/unibox/stream` (server-sent events) is **browser-only** and rejects API > keys. For server-side updates use [webhooks](/api-reference/endpoint/create-webhook) — > `message.reply` fires on every inbound message. ## Error responses | Status | When | | - | - | | `401` | Missing or invalid key | | `403` | An agency key (`tucoagency_…`) was used — this is per-workspace | # Create / Upload Lead Endpoint Source: https://docs.tuco.ai/api-reference/endpoint/create POST /api/leads Create one lead or bulk-upload many leads into a Tuco workspace in a single request, like a CSV import. Optional listId files them into a list. ## Endpoint * **Method**: `POST` * **Path**: `/api/leads` This endpoint is used both for creating a single lead and for bulk uploads (multiple leads in one request), just like the CSV import in the Tuco app. *** ## Request body **leads** `object[]` *required* One or more contacts. A single contact is a one-element array. `body` is accepted as an alias for this field. **lead fields** **phone** `string` **The phone number, in E.164** (e.g. `"+12025551234"`). This is the identifier that matters — it is how the lead is deduplicated, and how you text them later. Numbers without a country code are normalized using `defaultCountryCode`. **firstName** `string` First name. Used for message personalization. **lastName** `string` Last name. **email** `string` Email address. Lowercased before dedup. **companyName** `string` Company name. **jobTitle** `string` Job title. **notes** `string` Free-text notes. **linkedinUrl** `string` LinkedIn profile URL. **altPhone1** `string` Alternate phone 1. Tried when the primary number is not reachable, and counted for dedup. **altPhone2** `string` Alternate phone 2. **altPhone3** `string` Alternate phone 3. **altEmail1** `string` Alternate email 1. **altEmail2** `string` Alternate email 2. **altEmail3** `string` Alternate email 3. **customFields** `object` Free-form key/value data. See [custom field keys](/api-reference/endpoint/custom-field-keys) for the ones already in use. **contactOwnerEmail** `string` Email of the workspace user who owns this contact. Falls back to the first user in the workspace when omitted or unrecognised. **listId** `string` The list these leads belong to, from [`GET /api/lists`](/api-reference/endpoint/list-lists). Omit to use the **Quick Sends** list. An id that does not exist returns `404`. **defaultCountryCode** `string` (default: +1) Used to normalize phone numbers that arrive without a country code, e.g. `"+44"`. **source** `string` Origin label stored on each lead, e.g. `"api"` or `"gohighlevel"`. **ghlLocationId** `string` GoHighLevel location id, stored on the created leads when syncing from GHL. **contactOwnerEmail** `string` Applies an owner to every lead in the request. A per-lead `contactOwnerEmail` wins over this. ### Example body ```json theme={null} { "leads": [ { "firstName": "John", "lastName": "Doe", "email": "john@example.com", "phone": "+12025551234", "companyName": "Acme Corp", "jobTitle": "CEO", "notes": "Warm intro from Sarah", "contactOwnerEmail": "rep@yourcompany.com", "customFields": { "industry": "Technology", "segment": "Mid-market" } } ], "listId": "507f1f77bcf86cd799439011", "source": "api", "defaultCountryCode": "+1" } ``` * `leads` – one or more contacts; a single contact is just a one‑element array. * `listId` – **Optional.** Tuco list that should own these leads. Omit to use the **Quick Sends** list. * `source` – optional origin label (for example, `"api"` or `"gohighlevel"`). * `defaultCountryCode` – used to normalize phone numbers when no country code is present. * `ghlLocationId` – optional; used when syncing with GoHighLevel. * `contactOwnerEmail` – Email of the workspace user who owns this contact. If omitted or invalid, defaults to the first user in the workspace. * You may send `body` as an alias for `leads` (same array shape). *** ## Response **Success** – status `201 Created` when at least one lead was created, or `200 OK` when the request succeeded but no new leads were inserted. Example: ```json theme={null} { "message": "Leads saved successfully", "savedCount": 1, "duplicateCount": 0, "totalProcessed": 1, "listId": "507f1f77bcf86cd799439011", "leadId": "674a1b2c3d4e5f678901234a", "leadIds": ["674a1b2c3d4e5f678901234a"], "leadListIds": ["507f1f77bcf86cd799439011"], "ghlContactId": null, "ghlLocationId": null, "hsPortalId": null, "hsContactId": null } ``` Response fields: * `savedCount` – number of new leads actually inserted. * `duplicateCount` – leads skipped as duplicates within the same list (email/phone‑based). * `totalProcessed` – total rows you attempted to upload. * `listId` – list the leads were added to. * `leadIds` – array of Tuco lead IDs for **newly created** leads only, in the same order as inserted. Use these to link created leads back to your system or to fetch/update them later. * `leadListIds` – array of list IDs the new leads were added to (one list per request; same as `listId` when adding to a single list). * `duplicates` – present only when some (but not all) leads were duplicates; each entry describes the submitted input and the existing lead in the list. **All duplicates** – status **`200 OK`** (not 409). No new leads are created; the body includes `duplicateOnly: true`, `duplicateCount`, `totalProcessed`, `leadId` (first existing), `existingLeadIds`, `leadIds`, `duplicates` (each with `input` and `existingLead` including `_id`), and integration IDs (`ghlContactId`, `ghlLocationId`, etc.) so you can reconcile with existing records and continue your workflow (e.g. n8n). **Other errors:** Validation failures return `400` with a readable error. If the requested list does not exist, you get `404`. If the workspace is temporarily read‑only (e.g. payment past due), you get `402` with `code: "READ_ONLY"`. See `/api-reference/errors` for more. # Create Goal Bot Source: https://docs.tuco.ai/api-reference/endpoint/create-goal-bot POST /api/goal-bots Create a goal bot: one prompt, the tools it may use, and the tags that fire it. No stages. Pass status paused to create it dormant. > [!NOTE] > > **Goal bots and task agents are the same object.** The two engines merged; `/api/goal-bots` > and `/api/tasks` are aliases over one collection and return identical bodies. Every response > carries both `goalBot` and `taskAgent` (or `goalBots` and `taskAgents`) so integrations written > against either name keep working. > > The older stage-based engine moved to [`/api/instructions`](/api-reference/endpoint/list-instruction-bots) > and is being retired. A goal bot is one prompt plus the tags that wake it. There are no stages — tag a lead and the bot handles their replies. > [!WARNING] > > A new bot is **live the moment it is created** and will start answering leads whose tags already > match. Pass `"status": "paused"` if you want to create it, read it back, and switch it on > deliberately. ## Authentication Pass your workspace API key as a Bearer token, or use a Clerk session token. ```bash theme={null} Authorization: Bearer tuco_xxxxxxxxxxxxx ``` *** ## Request body **name** `string` *required* Display name for the bot. An empty or missing name returns `400 Name is required`. **prompt** `string` *required* The instructions the model runs on — who it is, what it is trying to do, what it must not say. An empty or missing prompt returns `400 Prompt is required`. **includeTags** `string[]` Tags that wake this bot. A lead carrying any of them is handled by this bot when it replies. Set tags with [`PATCH /api/leads/{id}`](/api-reference/endpoint/update-lead). Defaults to `[]`. **excludeTags** `string[]` Tags that keep a lead away from this bot, even when `includeTags` matches. Defaults to `[]`. **mode** `string` (default: autopilot) How replies are delivered. | Value | Behaviour | | - | - | | `autopilot` | The bot replies on its own. | | `copilot` | Every reply is saved as a draft for a human to approve. | | `manual` | The bot is off. This is the only way to stop the built-in **Auto Replies** bot, which cannot be deleted. | | `draft` | Legacy alias for `copilot`, still accepted. | > [!WARNING] > > An unrecognised value is **not** rejected — it is silently stored as `copilot`. Read the > `mode` back from the response to confirm what was saved. **status** `string` (default: active) `active` or `paused`. A new bot goes live the moment it exists and starts answering leads whose tags already match, so pass `"paused"` when you want to create, inspect, then flip it on with [`PATCH`](/api-reference/endpoint/update-goal-bot). Any value other than `"paused"` is stored as `active`. **connector** `string` (default: calendly) Calendar used for booking: `calendly` or `ghl_calendar`. Any other value falls back to `calendly`. **kbRetrieval** `string` (default: always) When the bot searches your knowledge base. `always` searches on every inbound message; `auto` leaves the decision to the model. On create, anything other than `"auto"` is stored as `always`. **tone** `string` Free-text tone hint, e.g. `"warm and brief"`. **canAsk** `boolean` (default: true) Whether the bot may ask the lead follow-up questions. Only an explicit `false` turns it off. **typingIndicator** `boolean` (default: true) Send a typing signal before replying. Only an explicit `false` turns it off. **maxTurns** `number` (default: 8) How many times the bot may reply in one conversation. Clamped to `1`–`20`; a non-numeric or non-positive value falls back to `8`. **onDoneTag** `string` Tag applied to the lead when the bot reaches its goal. **writeTagToCrm** `boolean` (default: false) Push `onDoneTag` to the connected CRM as well as to Tuco. Only an explicit `true` enables it. **allowedToolIds** `string[]` Ids of the API tools this bot may call, from [`GET /api/campaign-tools`](/api-reference/endpoint/list-tools). Omit to allow none. **collectFields** `string[]` Field names the bot should try to collect during the conversation, e.g. `["email", "company"]`. *** ## Example ```bash theme={null} curl -X POST "https://app.tuco.ai/api/goal-bots" \ -H "Authorization: Bearer tuco_xxxxxxxxxxxxx" \ -H "Content-Type: application/json" \ -d '{ "name": "Demo follow-up", "prompt": "You are Raj from Tuco. Book a 15-minute demo. Never quote a price.", "includeTags": ["demo-requested"], "excludeTags": ["customer"], "mode": "copilot", "status": "paused", "maxTurns": 6, "onDoneTag": "demo-booked", "collectFields": ["email"] }' ``` ### Success (`200 OK`) ```json theme={null} { "goalBot": { "_id": "6ac3ed5f71adb32c88d566df", "workspaceId": "org_3CzFir0Fps4hHL4nbU9WQ6FR4ur", "name": "Demo follow-up", "prompt": "You are Raj from Tuco. Book a 15-minute demo. Never quote a price.", "connector": "calendly", "includeTags": ["demo-requested"], "excludeTags": ["customer"], "mode": "copilot", "kbRetrieval": "always", "canAsk": true, "maxTurns": 6, "onDoneTag": "demo-booked", "collectFields": ["email"], "writeTagToCrm": false, "typingIndicator": true, "status": "paused", "createdAt": "2026-10-05T18:33:03.511Z", "updatedAt": "2026-10-05T18:33:03.511Z" }, "taskAgent": { /* identical object */ } } ``` > [!NOTE] > > The response is `200`, not `201`. Read `goalBot._id` and use it on every `{id}` route. *** ## Errors | Status | When | Body | | - | - | - | | `400` | `name` missing or blank | `{ "error": "Name is required" }` | | `400` | `prompt` missing or blank | `{ "error": "Prompt is required" }` | | `400` | Key has no active workspace | `{ "error": "No active workspace" }` | | `401` | Missing or invalid API key | `{ "error": "Unauthorized" }` | # Create Line Request Source: https://docs.tuco.ai/api-reference/endpoint/create-line-request POST /api/line-requests Create a new phone or email line request for the authenticated workspace. REST endpoint in the Tuco AI iMessage API — bearer-token auth, JSON request/response. > [!WARNING] > > **The Try it panel runs against production** (`https://app.tuco.ai`) with the key you paste > into it. There is no sandbox — a request from this page creates a real line request, and can start a real payment. > [!NOTE] > > Use this endpoint after the workspace already has an active Tuco subscription. If the request is included in the current plan, Tuco starts provisioning immediately. If the request requires an add-on, Tuco returns a hosted invoice link. ## What This Endpoint Decides You send the line details once, and Tuco decides what should happen next. The response will always fall into one of these buckets: * `provisioning` Tuco accepted the request immediately and has started setting up the line. * `awaiting_payment` Tuco saved the request, but it needs payment before provisioning can begin. * `subscription_required` The workspace needs an active base plan before it can request lines. * `forbidden_line_type` The current plan does not allow that request, or the plan reached a hard cap with no paid expansion path. ## Authentication Pass your workspace API key as a Bearer token, or use a Clerk session token. ```bash theme={null} Authorization: Bearer tuco_xxxxxxxxxxxxx ``` *** ## Request body > [!WARNING] > > Every order must carry the legal name, the company name and an explicit anti-spam acceptance. > A purchased phone line (an eSIM) must also carry the full legal address, the eSIM country, the ZIP / > postal code to provision on, and the area-code acknowledgement. A request missing any of them is > rejected with `400` and **no line is created**. ### Who the line belongs to **legalFirstName** `string` *required* Required. First name of the person **authorised to make this payment on behalf of the company**. Agency ordering for a client? Use your client's name. Business owner? Use your own name. Marketing or ops? Use your name or the business owner's. Only the SIM card provider sees it — never your leads (they see the display name). **legalLastName** `string` *required* Required. Last name of the same authorised person (see `legalFirstName`). **displayFirstName** `string` Optional. Display first name — **set on the Mac** and shown to conversation participants on iMessage. If omitted, Tuco uses `legalFirstName`. `firstName` is accepted as an alias. **displayLastName** `string` Optional. Display last name — **set on the Mac** and shown to conversation participants on iMessage. If omitted, Tuco uses `legalLastName`. `lastName` is accepted as an alias. **companyName** `string` *required* Required for every line. The company's legal name — an LLC, Inc, sole proprietorship or any registered business, anywhere in the world, e.g. `"Acme, LLC"` or `"Acme, Inc."`. `legalName` is accepted as an alias. **companyPhone** `string` Optional. Business contact number for the company (not the line's own number). **antiSpamAccepted** `boolean` *required* Required for every line. Must be the boolean `true`, confirming the workspace accepts Tuco's [anti-spam and messaging rules](https://tuco.ai/anti-spam-policy). Any other value — including `"true"` as a string — is treated as not accepted. Those rules include: every lead sees Delete / Delete and Report Spam / Mark as Known on **every** message until they save you; no old leads who've forgotten you, no high-pressure tactics, nobody who opted in more than a month ago; and when re-engaging older leads, a different message per lead with a 3–5 minute gap. See [What your leads see](/what-leads-see). ### What kind of line **channelType** `string` *required* Supported values: `"phone"` or `"email"`. Defaults to `"phone"`. **lineType** `string` Optional. Supported values: `"purchased"` or `"byon"`. Defaults to `"purchased"` when omitted. Send `"byon"` (bring your own number) **only if you are porting a number you already own**. Leave it out to have Tuco provision a new number on an eSIM. **email** `string` Required for email lines, and for phone lines you are porting (`lineType: "byon"`). Leave it out for a purchased phone line. **phone** `string` **Not required unless you are porting a number you already own** (`lineType: "byon"`), in which case send it in E.164 form, e.g. `"+14155550123"`. For a purchased phone line — the normal case — **omit this field entirely**. Tuco assigns the number and reports it back once provisioning completes. > [!WARNING] > > Do not send a placeholder such as `"pending"`, `"none"` or `""` to satisfy the field. Whatever you > send is stored as the line's number, so a placeholder makes the line look like it already has one. > Omitting the field is what marks the number as not yet assigned. ### eSIM fields (purchased phone lines) Required when `channelType` is `"phone"` and `lineType` is `"purchased"` (or omitted). Ignored for email lines and ported numbers. **simCountry** `string` *required* Country the eSIM is for: `"US"` or `"CA"`. eSIMs are self-serve for the **US and Canada only** — for the UK, Australia or any other country, contact [support@tuco.ai](mailto:support@tuco.ai). Any other value is rejected with `400`. > [!NOTE] > > **iMessage works globally** — a US or Canadian line can iMessage recipients in any country. > **P2P SMS fallback** (a green bubble sent from this same number when the recipient isn't on > iMessage) only reaches recipients **in the eSIM's country**: a `US` eSIM falls back to SMS for US > numbers only, a `CA` eSIM for Canadian numbers only. **addressLine1** `string` *required* Street of the **legal service address** — it can be anywhere in the world. Carriers need a real address to activate the eSIM. The number itself is provisioned on `zipcode` (US or Canada). **addressLine2** `string` Optional. Apt / suite / unit. **city** `string` *required* City of the legal service address. **state** `string` *required* State (US) or province (Canada) of the legal service address, e.g. `"CA"` or `"ON"`. **legalZipcode** `string` *required* ZIP (US) or postal code (Canada) of the legal service address. Not format-checked. **zipcode** `string` *required* ZIP / postal code **to provision the number on**. The eSIM number is requested on this ZIP — **not** on an area code. It can be different from `legalZipcode`. Not format-checked. **areaCodeBestEffortAcknowledged** `boolean` *required* Must be the boolean `true`. Confirms you understand the area code is **best effort**: Tuco does not guarantee an area code — the eSIM is provisioned on the `zipcode` you provide, not an area code, and the legal address and that ZIP can be different. **preferredAreaCode** `string` Optional. **Leave it out (the default) to accept any area code that matches `zipcode`.** Send it only if you'd like a specific area code, as 3 digits (e.g. `"212"`). **Best effort — NOT guaranteed.** We try for it, but the number is provisioned on `zipcode` and you may get a different area code. It never delays the order. Anything that isn't a 3-digit US / Canada area code returns `400`. > [!WARNING] > > **An area code is never guaranteed**, whether or not you send `preferredAreaCode`. Don't promise a > specific area code to anyone before the line is live. ### Calling add-ons (optional, phone lines) Every phone line includes 500 outgoing minutes/month with recording, unlimited incoming, and \$3 per extra 100 minutes. These per-line add-ons are optional — see [Calling add-ons](/api-reference/endpoint/calling-addons). **callingAddons** `string[]` Any of `"facetime_audio"` (FaceTime Audio add-on — $100/mo per line) and `"caller_id_registration"` (Registered caller ID add-on — $50 setup + $50/mo per line + $0.075 per call). Charged right after the line is created, to the card on file: the setup fee plus today's prorated share of the monthly, then monthly. Add-ons can't be removed after purchase — contact [support@tuco.ai](mailto:support@tuco.ai). Add-ons already bought with your plan at checkout attach to new phone lines automatically, with no second charge. You don't need to list them. If you do list one that is still unused, it is used first and not charged again. `reviewOnly` shows both cases as **Paid at checkout, no new charge**. [Calling Add-on Slots](/api-reference/endpoint/calling-addon-slots) shows how many are left. Registered caller ID also needs the workspace's [caller ID details](/api-reference/endpoint/caller-id-profile) before it can go live. The line is created either way. **acceptCallingAddonCharges** `boolean` Required (`true`) whenever `callingAddons` is non-empty — your explicit agreement to those charges. Non-refundable. Without it the request is rejected with `400` and nothing is created. The response then includes a `callingAddons` array — one result per add-on, with `status` `pending_setup` (charged to the card on file; we're setting it up) or, only when the card is declined or the bank requires authentication (3-D Secure), `awaiting_payment` plus a `paymentUrl` for the customer to confirm the payment. All of a line's add-ons are charged together: one invoice, so every `awaiting_payment` result carries the same `paymentUrl`, and one confirmation starts them all. The link lapses after about 23 hours if unpaid; the add-ons then go back to `none`. Add-ons that came from one you already paid for at checkout, including ones attached automatically, are listed too, with `usedPrepaidSlot: true` and `chargedCents: 0`. ### Other **forwardCallsTo** `string` Optional. Forwarding destination for inbound calls on phone lines. One line = one forwarding number. **profileImageUrl** `string` Optional. Avatar shown in Tuco. > [!WARNING] > > **Review everything and be sure.** Ordering is free — the name and photo you send here don't count. > After the line is created, its display name and photo can change at most **3 times per line per month** — each change needs a person on our side to update the Mac. A > 4th change in the same month returns `400` (`LINE_INFO_UPDATE_LIMIT`); contact [support@tuco.ai](mailto:support@tuco.ai). > Use `reviewOnly` below to check everything first. **reviewOnly** `boolean` Optional. Send `true` to **review the order without creating it**. Tuco runs exactly the same validation as a real order and returns `200` with a `review` object — the display name and photo your leads will see, the legal name, company, eSIM country, legal address, provisioning ZIP, forwarding number, calling add-ons with their charges, and a `recipientPreviewUrl` showing Apple's "Maybe: (your name)" screens. Nothing is created or charged. Change anything and review again, then send the same body without `reviewOnly` to order. Missing or invalid fields return `400` with `missingFields`, as on a real order. **idempotencyKey** `string` Optional. You can also send this as the `Idempotency-Key` header. Reusing the same key returns the original response instead of creating a duplicate request. *** ## Required field rules Every request needs `legalFirstName`, `legalLastName`, `companyName` and `antiSpamAccepted: true`. On top of that: | Request type | Also required | Leave out | | - | - | - | | Purchased phone line / eSIM (most common) | `channelType=phone`, `simCountry`, `addressLine1`, `city`, `state`, `legalZipcode`, `zipcode`, `areaCodeBestEffortAcknowledged: true` | `phone`, `email`, `lineType` | | Email line | `channelType=email`, `email` | `phone` | | Porting a number you own | `channelType=phone`, `lineType=byon`, `email`, `phone` | — | `displayFirstName` / `displayLastName` are always optional — each falls back to the legal name. Extra fields are tolerated, so an unexpected field will not fail the request — but a value you send is a value Tuco stores. Leave out the fields your request type does not use rather than filling them with placeholders. ### Default behavior for phone lines If `channelType` is `phone` and `lineType` is omitted, Tuco treats the request as: ```json theme={null} { "lineType": "purchased" } ``` That means the eSIM fields are required unless you explicitly send `lineType: "byon"`. *** ## Example: included line (eSIM) ```bash theme={null} curl -X POST "https://app.tuco.ai/api/line-requests" \ -H "Authorization: Bearer tuco_xxxxxxxxxxxxx" \ -H "Content-Type: application/json" \ -H "Idempotency-Key: line-req-001" \ -d '{ "legalFirstName": "Jane", "legalLastName": "Doe", "displayFirstName": "Jane", "displayLastName": "from Acme", "companyName": "Acme, LLC", "antiSpamAccepted": true, "channelType": "phone", "simCountry": "US", "addressLine1": "123 Market St", "city": "San Francisco", "state": "CA", "legalZipcode": "94103", "zipcode": "10001", "preferredAreaCode": "212", "areaCodeBestEffortAcknowledged": true }' ``` ### Success: provisioning (`201 Created`) ```json theme={null} { "success": true, "status": "provisioning", "paymentRequired": false, "line": { "_id": "6a091e74542d9e3d645925ae", "firstName": "Jane", "lastName": "from Acme", "channelType": "phone", "lineType": "purchased", "provisioningStatus": "provisioning", "paymentStatus": "not_required" }, "recipientPreviewUrl": "https://app.tuco.ai/recipient-preview?name=Jane%20from%20Acme" } ``` `recipientPreviewUrl` is returned on **every** order: a hosted preview of exactly what a lead sees from this line — Apple's "Maybe: Jane from Acme" header with **Delete**, **Delete and Report Spam** and **Mark as Known** on every message until they save your contact. Show it to whoever writes your messages. See [What your leads see](/what-leads-see). `line.firstName` / `line.lastName` are the **display** name — what the Mac shows participants. *** ## Example: paid add-on line ```bash theme={null} curl -X POST "https://app.tuco.ai/api/line-requests" \ -H "Authorization: Bearer tuco_xxxxxxxxxxxxx" \ -H "Content-Type: application/json" \ -H "Idempotency-Key: line-req-002" \ -d '{ "legalFirstName": "Sam", "legalLastName": "Support", "companyName": "Acme, LLC", "antiSpamAccepted": true, "channelType": "email", "email": "support2@example.com" }' ``` No display name is sent, so the line shows `Sam Support`. ### Success: awaiting payment (`201 Created`) ```json theme={null} { "success": true, "status": "awaiting_payment", "paymentRequired": true, "paymentReason": "over_plan_limit", "paymentUrl": "https://invoice.stripe.com/...", "expiresAt": null, "line": { "_id": "6a09279daa903300e2530b0f", "firstName": "Sam", "lastName": "Support", "channelType": "email", "lineType": "purchased", "provisioningStatus": "awaiting_payment", "paymentStatus": "awaiting_payment", "stripeInvoiceId": "in_123", "paymentLinkUrl": "https://invoice.stripe.com/..." }, "recipientPreviewUrl": "https://app.tuco.ai/recipient-preview?name=Sam%20Support" } ``` *** ## Example: review before ordering (`reviewOnly`) Send the same body with `"reviewOnly": true`: ```json theme={null} { "reviewOnly": true, "created": false, "review": { "displayName": "Venk - ABA Therapy", "legalName": "Venkat Raman", "companyName": "ABA Therapy, LLC", "channelType": "phone", "lineType": "purchased", "profileImageUrl": "https://cdn.example.com/venk.jpg", "simCountry": "United States", "legalAddress": "123 Market St, San Francisco, CA, 94103, US", "provisioningZip": "10001", "preferredAreaCode": { "value": "212", "guaranteed": false, "note": "Preference only — NOT guaranteed. We try for this area code, but the number is provisioned on your ZIP / postal code and you may get a different area code. It never delays your order." }, "forwardCallsTo": "+16285559999", "callingAddons": [ { "key": "facetime_audio", "label": "FaceTime Audio add-on", "price": "$100/mo per line", "paidAtCheckout": false, "requested": true }, { "key": "caller_id_registration", "label": "Registered caller ID add-on", "price": "Paid at checkout, no new charge", "paidAtCheckout": true, "requested": false } ], "callingAddonChargesToday": "$100/mo, prorated today", "recipientPreviewUrl": "https://app.tuco.ai/recipient-preview?name=Venk%20-%20ABA%20Therapy&photo=https%3A%2F%2Fcdn.example.com%2Fvenk.jpg", "whatTheLeadSees": "Until they save your contact or tap Mark as Known, every message from this line shows \"Maybe: Venk - ABA Therapy\" with Delete, Delete and Report Spam, and Mark as Known." } } ``` Open `recipientPreviewUrl` to see exactly what your leads will see. Wrong name or photo? Change `displayName*` / `profileImageUrl` and review again. `callingAddons` lists every add-on the new line will get, priced the way the order charges it: * `paidAtCheckout: true` means an add-on you already paid for at checkout covers it. Its `price` is "Paid at checkout, no new charge", and it isn't part of `callingAddonChargesToday`. * `requested: false` means you didn't list it, but it attaches automatically because you paid for it at checkout. * `callingAddonChargesToday` is `null` when nothing will be charged today. ## Example: rejected — missing compliance fields (`400`) ```json theme={null} { "error": "Missing required fields: legalFirstName, legalLastName, companyName, antiSpamAccepted, addressLine1, city, state, legalZipcode, zipcode, simCountry, areaCodeBestEffortAcknowledged", "missingFields": [ "legalFirstName", "legalLastName", "companyName", "antiSpamAccepted", "addressLine1", "city", "state", "legalZipcode", "zipcode", "simCountry", "areaCodeBestEffortAcknowledged" ] } ``` *** ## What To Do After You Create A Request If the response is `provisioning`: * keep the returned `line._id` * poll `GET /api/line-requests/{id}` for status updates If the response is `awaiting_payment`: * keep the returned `line._id` * show the `paymentUrl` to the user * after payment, poll `GET /api/line-requests/{id}` until it changes to `provisioning` You should not submit the same line details again after payment. The original request is the one that continues. *** ## One Request At A Time Tuco blocks a new request only when the workspace already has a line request in `awaiting_payment`. This prevents: * duplicate unpaid requests * accidental double purchases * race conditions from retries Lines already in `provisioning` do not block the next request. *** ## Error responses | Status | When | Body | | - | - | - | | `400` | Missing or invalid order fields (legal name, company, anti-spam, eSIM address / country / ZIPs / area-code acknowledgement) | `{ "error": "...", "missingFields": ["..."] }` | | `400` | `simCountry` other than `US` / `CA` — contact [support@tuco.ai](mailto:support@tuco.ai) for other countries | `{ "error": "...", "missingFields": [] }` | | `401` | Missing or invalid API key / session | `{ "error": "Unauthorized" }` | | `403` | Workspace has no active subscription | `{ "success": false, "status": "subscription_required", "message": "...", "redirect": "/billing" }` | | `403` | Line type is not allowed on the plan, or hard cap reached with no paid expansion | `{ "success": false, "status": "forbidden_line_type", "message": "..." }` | | `409` | Another line request is already waiting for payment | `{ "success": false, "status": "request_in_progress", "message": "...", "existingLine": { ... } }` | | `429` | Rate limit exceeded | `{ "error": "Rate limit exceeded", "retryAfterMs": 1234 }` | *** ## Notes * Payment is always attached to the exact saved line request. The caller does not need to resubmit the payload after paying. * The API uses the authenticated workspace. You cannot request lines for an arbitrary workspace id in the body. * Retry safety is built in through idempotency support and workspace-level request locking. # Create Lead List Source: https://docs.tuco.ai/api-reference/endpoint/create-list POST /api/lists Create a lead list in your Tuco workspace, optionally seeding it with contacts. Returns the listId used by the leads and availability endpoints. > [!NOTE] > > A **list** owns leads. `listId` is what you pass to > [`POST /api/leads`](/api-reference/endpoint/create) to file new leads somewhere specific, and to > [`POST /api/leads/check-availability`](/api-reference/endpoint/bulk-check-availability) to check a > whole list at once. These endpoints are how you get a `listId` without opening the dashboard. Creates an empty list, or creates one and fills it in the same call by passing `contacts`. ## Authentication Pass your workspace API key as a Bearer token, or use a Clerk session token. ```bash theme={null} Authorization: Bearer tuco_xxxxxxxxxxxxx ``` *** ## Request body **name** `string` *required* List name. **Must be unique in the workspace** — a duplicate returns `400 List name already exists` with `code: "NAME_EXISTS"`. A missing or non-string name returns `400` with `code: "NAME_REQUIRED"`. **description** `string` Optional description. **contacts** `object[]` Optional. Seed the list with leads in the same call. Same per-lead shape as [`POST /api/leads`](/api-reference/endpoint/create) — `firstName`, `lastName`, `phone`, `email`, `companyName`, `customFields`, and so on. Prefer `phone` in E.164 as the identifier. When present, the response is the **import** shape (`listId`, `savedCount`, `duplicateCount`) rather than the list object. **source** `string` (default: api) Origin label stored on the created leads, e.g. `"api"` or `"gohighlevel"`. Only used with `contacts`. **ghlLocationId** `string` GoHighLevel location id, stored on the created leads. Only applied when `source` is `"gohighlevel"`. *** ## Example — empty list ```bash theme={null} curl -X POST "https://app.tuco.ai/api/lists" \ -H "Authorization: Bearer tuco_xxxxxxxxxxxxx" \ -H "Content-Type: application/json" \ -d '{ "name": "Q4 outbound", "description": "Sourced from the October webinar" }' ``` ### Success (`200 OK`) ```json theme={null} { "message": "List created successfully", "list": { "_id": "6ac3f1a271adb32c88d566f1", "name": "Q4 outbound", "description": "Sourced from the October webinar", "workspaceId": "org_3CzFir0Fps4hHL4nbU9WQ6FR4ur", "leadCount": 0, "createdAt": "2026-10-05T19:02:10.004Z", "updatedAt": "2026-10-05T19:02:10.004Z" } } ``` ## Example — create and seed in one call ```bash theme={null} curl -X POST "https://app.tuco.ai/api/lists" \ -H "Authorization: Bearer tuco_xxxxxxxxxxxxx" \ -H "Content-Type: application/json" \ -d '{ "name": "Q4 outbound", "contacts": [ { "firstName": "Jane", "lastName": "Doe", "phone": "+14155551234" } ] }' ``` ### Success (`200 OK`) ```json theme={null} { "listId": "6ac3f1a271adb32c88d566f1", "savedCount": 1, "duplicateCount": 0 } ``` > [!NOTE] > > Take `listId` from either response shape and pass it to > [`POST /api/leads`](/api-reference/endpoint/create) to add more leads later. *** ## Errors | Status | When | Body | | - | - | - | | `400` | `name` missing or not a string | `{ "error": "List name is required", "code": "NAME_REQUIRED" }` | | `400` | A list with that name already exists | `{ "error": "List name already exists", "code": "NAME_EXISTS" }` | | `400` | A contact row is invalid | `{ "error": "...", "code": "INVALID_LEADS" }` | | `401` | Missing or invalid API key | `{ "error": "Unauthorized" }` | | `402` | Subscription past due (workspace read-only) | `{ "error": "READ_ONLY", "code": "READ_ONLY", "reason": "past_due" }` | | `429` | More than 120 requests/min for this workspace | `{ "error": "Rate limit exceeded" }` | # Create Task Agent Source: https://docs.tuco.ai/api-reference/endpoint/create-task-agent POST /api/tasks Create a Tuco task agent (an alias of POST /api/goal-bots, since task agents and goal bots merged). Workspace API key or Clerk session token. > [!NOTE] > > **This is an alias.** `POST /api/tasks` and > [`POST /api/goal-bots`](/api-reference/endpoint/create-goal-bot) are the same route and take the > same body. The full field reference lives on > [Create Goal Bot](/api-reference/endpoint/create-goal-bot). ## Authentication Pass your workspace API key as a Bearer token, or use a Clerk session token. ```bash theme={null} Authorization: Bearer tuco_xxxxxxxxxxxxx ``` *** ## Request body **name** `string` *required* Display name. Blank returns `400 Name is required`. **prompt** `string` *required* The instructions the model runs on. Blank returns `400 Prompt is required`. **includeTags** `string[]` Tags that wake this agent. Defaults to `[]`. **excludeTags** `string[]` Tags that keep leads away from it. Defaults to `[]`. **mode** `string` (default: autopilot) `autopilot`, `copilot`, `manual`, or the legacy alias `draft`. An unrecognised value is stored as `copilot` rather than rejected. **status** `string` (default: active) `active` or `paused`. Pass `"paused"` to create it dormant, verify it, then flip it on. **connector** `string` (default: calendly) `calendly` or `ghl_calendar`. **kbRetrieval** `string` (default: always) `always` or `auto`. **tone** `string` Free-text tone hint. **canAsk** `boolean` (default: true) Whether it may ask follow-up questions. **typingIndicator** `boolean` (default: true) Send a typing signal before replying. **maxTurns** `number` (default: 8) Reply cap per conversation. Clamped to 1–20. **onDoneTag** `string` Tag applied when the agent finishes. **writeTagToCrm** `boolean` (default: false) Push `onDoneTag` to the connected CRM too. **allowedToolIds** `string[]` Tool ids the agent may call. **collectFields** `string[]` Fields the agent should try to collect. *** ## Example ```bash theme={null} curl -X POST "https://app.tuco.ai/api/tasks" \ -H "Authorization: Bearer tuco_xxxxxxxxxxxxx" \ -H "Content-Type: application/json" \ -d '{ "name": "Demo follow-up", "prompt": "You are Raj from Tuco. Book a 15-minute demo.", "includeTags": ["demo-requested"], "status": "paused" }' ``` ### Success (`200 OK`) ```json theme={null} { "goalBot": { "_id": "6ac3ed5f71adb32c88d566df", "name": "Demo follow-up", "status": "paused" }, "taskAgent": { /* identical object */ } } ``` *** ## Errors | Status | When | Body | | - | - | - | | `400` | `name` blank | `{ "error": "Name is required" }` | | `400` | `prompt` blank | `{ "error": "Prompt is required" }` | | `400` | Key has no active workspace | `{ "error": "No active workspace" }` | | `401` | Missing or invalid API key | `{ "error": "Unauthorized" }` | # Create Webhook Source: https://docs.tuco.ai/api-reference/endpoint/create-webhook POST /api/webhooks Register a new webhook endpoint — the signing secret is returned once. REST endpoint in the Tuco AI iMessage API — bearer-token auth, JSON request/response. Register a URL to receive real-time event notifications. The HMAC signing secret is returned **once** in the response. Save it immediately — you can't retrieve it later. ## Authentication ```bash theme={null} Authorization: Bearer tuco_xxxxxxxxxxxxx ``` *** ## Request body **url** `string` *required* HTTPS endpoint URL that will receive webhook POSTs. **events** `string[]` *required* Event types to subscribe to. At least one required. | Event | When fired | | - | - | | `message.sent` | Message accepted by Tuco | | `message.failed` | Message failed after retries | | `message.fallback` | Recipient has no iMessage | | `message.reply` | Lead replied | | `message.opened` | Message read (read receipt) | | `message.reaction` | Lead reacted (tapback) | | `message.ai_draft` | AI copilot drafted a reply for review | | `message.ai_draft_approved` | Draft approved & sent (any channel) | | `message.ai_draft_rejected` | Draft rejected (any channel) | | `conversation.handover` | The AI SDR handed the conversation to a human and stopped replying | | `call.recording.ready` | A call recording is stored and downloadable (once per call) | | `dnc.added` | A contact was added to your Do-Not-Contact list (replied STOP, or added by you) | | `group.message.received` | Someone sent a message in an iMessage group your line is in | | `group.message.sent` | Your message landed in a group | | `group.message.failed` | Your message to a group failed | | `group.message.reaction` | Someone in a group reacted to a message | **name** `string` *required* User-friendly name for this webhook. **description** `string` Optional description. *** ## Response **id** `string` Webhook ID **secret** `string` HMAC-SHA256 signing secret. **Shown once.** Use this to verify `X-Tuco-Signature` on incoming webhooks. **url** `string` Endpoint URL **events** `string[]` Subscribed events **name** `string` Webhook name **createdAt** `string` Creation timestamp (ISO UTC) **warning** `string` Reminder to save the secret *** ## Examples ```bash All events theme={null} curl -X POST "https://app.tuco.ai/api/webhooks" \ -H "Authorization: Bearer tuco_xxxxxxxxxxxxx" \ -H "Content-Type: application/json" \ -d '{ "url": "https://example.com/webhooks/tuco", "events": ["message.sent", "message.failed", "message.fallback", "message.reply", "message.reaction", "message.opened", "message.ai_draft", "message.ai_draft_approved", "message.ai_draft_rejected", "conversation.handover"], "name": "Production webhook" }' ``` ```bash Replies only theme={null} curl -X POST "https://app.tuco.ai/api/webhooks" \ -H "Authorization: Bearer tuco_xxxxxxxxxxxxx" \ -H "Content-Type: application/json" \ -d '{ "url": "https://example.com/webhooks/replies", "events": ["message.reply"], "name": "Reply listener", "description": "Forwards replies to Slack" }' ``` ```json 201 Response theme={null} { "id": "680a1b2c3d4e5f6789012345", "secret": "dGhpcyBpcyBhIHNhbXBsZSBzZWNyZXQ=", "url": "https://example.com/webhooks/tuco", "events": ["message.sent", "message.failed", "message.fallback", "message.reply", "message.reaction", "message.opened", "message.ai_draft", "message.ai_draft_approved", "message.ai_draft_rejected", "conversation.handover"], "name": "Production webhook", "description": null, "createdAt": "2026-04-12T12:00:00.000Z", "warning": "Save this secret now. You will not be able to see it again." } ``` > [!WARNING] > > Copy the `secret` from the response and store it securely (e.g. environment variable). > This is the **only time** it's returned. If you lose it, delete the webhook and create a new one. *** ## Errors | Status | When | | - | - | | `400` | URL missing, invalid URL format, no events, invalid event types, name missing | | `401` | Invalid or missing API key | | `402` | Subscription past due (workspace is read-only) | # List Custom Field Keys Source: https://docs.tuco.ai/api-reference/endpoint/custom-field-keys GET /api/leads/custom-field-keys Discover the customFields keys actually in use on your Tuco leads, so you can write the right ones in PATCH /api/leads/{id} and in message variables. > [!NOTE] > > `customFields` is free-form, so nothing tells you which keys a workspace already uses. This returns > the ones in use with a count, so you can write the right key in > [`PATCH /api/leads/{id}`](/api-reference/endpoint/update-lead) instead of guessing and creating a > near-duplicate. ## Authentication Pass your workspace API key as a Bearer token, or use a Clerk session token. ```bash theme={null} Authorization: Bearer tuco_xxxxxxxxxxxxx ``` *** ## Example ```bash theme={null} curl "https://app.tuco.ai/api/leads/custom-field-keys" \ -H "Authorization: Bearer tuco_xxxxxxxxxxxxx" ``` ### Success (`200 OK`) ```json theme={null} { "keys": [ { "name": "Industry", "count": 6 }, { "name": "Contract Value", "count": 3 }, { "name": "close_owner_id", "count": 8 } ] } ``` > [!WARNING] > > **This is a sample, not an exhaustive index.** The scan is bounded to keep it cheap on large > workspaces: at most 2,000 lead documents are inspected and at most 200 keys returned. A rarely-used > key may be missing from the list — and it still works. `customFields` accepts any key, and > `{cf:Anything}` resolves at send time whether or not it appears here. ## Response **keys** `object[]` Custom-field keys found in the sample. **Key fields** **name** `string` The key, exactly as stored — matching is case-sensitive. **count** `number` How many sampled leads carry it. > [!NOTE] > > On an internal error this endpoint returns `200` with `{ "keys": [] }` rather than failing — it is > a discovery aid, and an empty list must not break a page that calls it. *** ## Errors | Status | When | Body | | - | - | - | | `400` | Key has no active workspace | `{ "error": "No active workspace" }` | | `401` | Missing or invalid API key | `{ "error": "Unauthorized" }` | # Delete Lead Endpoint Source: https://docs.tuco.ai/api-reference/endpoint/delete DELETE /api/leads Delete one or more leads from a Tuco workspace by id. Ids outside your workspace are ignored, not errors, and deletedCount reports what was removed. > [!WARNING] > > **The Try it panel runs against production** (`https://app.tuco.ai`) with the key you paste > into it. There is no sandbox — a request from this page permanently deletes real leads. ## Endpoint * **Method**: `DELETE` * **Path**: `/api/leads` *** ## Request body **ids** `string[]` *required* Lead ids to delete, from [`GET /api/leads`](/api-reference/endpoint/get). Ids that are not in your workspace are ignored rather than erroring — only matching leads count toward `deletedCount`. An empty or missing array returns `400 No ids provided`. ```json theme={null} { "ids": [ "667f1f77bcf86cd799439012", "667f1f77bcf86cd799439013" ] } ``` *** ## Behavior & Response When the request is accepted: * The specified leads stop appearing in normal Tuco views for your workspace. * They no longer participate in future sends or actions. * List counts are updated accordingly. **Success response** ```json theme={null} { "deletedCount": 2 } ``` If no IDs are provided you receive a `400` error. If some IDs do not belong to the workspace, they are ignored and only matching leads are counted in `deletedCount`. Tuco does not perform partial updates silently—either the document set for this workspace is updated as requested, or you receive a clear error explaining why nothing changed. # Delete Lead List Source: https://docs.tuco.ai/api-reference/endpoint/delete-list DELETE /api/lists Delete a Tuco lead list and choose whether the leads inside it are kept or deleted too. Bearer-token REST endpoint in the Tuco AI iMessage API. > [!WARNING] > > **The Try it panel runs against production** (`https://app.tuco.ai`) with the key you paste > into it. There is no sandbox — a request from this page permanently deletes a real list. > [!NOTE] > > A **list** owns leads. `listId` is what you pass to > [`POST /api/leads`](/api-reference/endpoint/create) to file new leads somewhere specific, and to > [`POST /api/leads/check-availability`](/api-reference/endpoint/bulk-check-availability) to check a > whole list at once. These endpoints are how you get a `listId` without opening the dashboard. > [!WARNING] > > The list id goes in the **request body**, not the URL. `DELETE /api/lists` with no body returns > `400 List ID is required`. Some HTTP clients drop bodies on `DELETE` by default — if you get that > error with an id you know is correct, that is why. ## Authentication Pass your workspace API key as a Bearer token, or use a Clerk session token. ```bash theme={null} Authorization: Bearer tuco_xxxxxxxxxxxxx ``` *** ## Request body **listId** `string` *required* The list to delete, from [`GET /api/lists`](/api-reference/endpoint/list-lists). **deleteLeads** `boolean` (default: false) What happens to the leads inside it. | Value | Result | | - | - | | `false` (default) | The list is removed; its leads stay in the workspace as unassigned. | | `true` | The leads are deleted too, along with their activities, messages and conversations. | > [!WARNING] > > `deleteLeads: true` is **permanent** and takes the conversation history with it. *** ## Example ```bash theme={null} curl -X DELETE "https://app.tuco.ai/api/lists" \ -H "Authorization: Bearer tuco_xxxxxxxxxxxxx" \ -H "Content-Type: application/json" \ -d '{ "listId": "6ac3f1a271adb32c88d566f1", "deleteLeads": false }' ``` ### Success (`200 OK`) ```json theme={null} { "message": "List deleted successfully", "deletedLeads": "leads moved to unassigned" } ``` With `deleteLeads: true`, `deletedLeads` reads `"all leads deleted"`. *** ## Errors | Status | When | Body | | - | - | - | | `400` | `listId` missing | `{ "error": "List ID is required" }` | | `401` | Missing or invalid API key | `{ "error": "Unauthorized" }` | | `404` | No list with that id in your workspace | `{ "error": "List not found" }` | # Delete Task Agent Source: https://docs.tuco.ai/api-reference/endpoint/delete-task-agent DELETE /api/tasks/{id} Permanently delete a Tuco task agent. Leads and conversations it already handled are unaffected. No request body; workspace API key auth. > [!WARNING] > > **The Try it panel runs against production** (`https://app.tuco.ai`) with the key you paste > into it. There is no sandbox — a request from this page permanently deletes a real agent. > [!NOTE] > > **This is an alias.** `DELETE /api/tasks/{id}` and > [`DELETE /api/goal-bots/{id}`](/api-reference/endpoint/archive-goal-bot) are the same route. Deletes the agent permanently. Conversations it already handled are untouched. There is no body. > [!WARNING] > > **The built-in Auto Replies agent cannot be deleted** — it is recreated on the next list call. > Deleting it returns `409`. Set its `mode` to `manual` to stop it instead. ## Authentication Pass your workspace API key as a Bearer token, or use a Clerk session token. ```bash theme={null} Authorization: Bearer tuco_xxxxxxxxxxxxx ``` *** ## Path parameter **id** `string` *required* The agent id. A malformed id returns `400 Invalid id`. *** ## Example ```bash theme={null} curl -X DELETE "https://app.tuco.ai/api/tasks/6ac3ed5f71adb32c88d566df" \ -H "Authorization: Bearer tuco_xxxxxxxxxxxxx" ``` ### Success (`200 OK`) ```json theme={null} { "success": true } ``` *** ## Errors | Status | When | Body | | - | - | - | | `400` | Malformed `{id}` | `{ "error": "Invalid id" }` | | `400` | Key has no active workspace | `{ "error": "No active workspace" }` | | `401` | Missing or invalid API key | `{ "error": "Unauthorized" }` | | `404` | No agent with that id in your workspace | `{ "error": "Not found" }` | | `409` | Target is the default **Auto Replies** agent | `{ "error": "The Auto Replies bot cannot be deleted. Set its mode to Off (manual) to stop it." }` | # Delete API Tool Source: https://docs.tuco.ai/api-reference/endpoint/delete-tool DELETE /api/campaign-tools Delete an API tool from your Tuco AI workspace — removes it from goal bots so it can no longer be invoked by AI replies. > [!WARNING] > > **The Try it panel runs against production** (`https://app.tuco.ai`) with the key you paste > into it. There is no sandbox — a request from this page permanently deletes a real tool. > [!NOTE] > > An API tool lets a goal bot call **your** endpoint mid-conversation — check stock, look up an > order, fetch a balance — and use the answer in its reply. Attach a tool to a bot by putting its > `_id` in that bot's `allowedToolIds`. > [!WARNING] > > The tool id goes in the **query string**, not the body — `?id=...`. There is no request body, and > a `DELETE` without `id` returns `400 Invalid tool id`. ## Authentication Pass your workspace API key as a Bearer token, or use a Clerk session token. ```bash theme={null} Authorization: Bearer tuco_xxxxxxxxxxxxx ``` *** ## Query parameter **id** `string` *required* The tool `_id` from [`GET /api/campaign-tools`](/api-reference/endpoint/list-tools). A missing or malformed id returns `400 Invalid tool id`. *** ## Example ```bash theme={null} curl -X DELETE "https://app.tuco.ai/api/campaign-tools?id=6ac3ed9271adb32c88d566e0" \ -H "Authorization: Bearer tuco_xxxxxxxxxxxxx" ``` ### Success (`200 OK`) ```json theme={null} { "ok": true } ``` > [!NOTE] > > Deleting a tool does not edit the bots that referenced it — a stale id left in a bot's > `allowedToolIds` is simply ignored. Clean it up with > [`PATCH /api/goal-bots/{id}`](/api-reference/endpoint/update-goal-bot) if you want the config tidy. *** ## Errors | Status | When | Body | | - | - | - | | `400` | `id` missing or malformed | `{ "error": "Invalid tool id" }` | | `401` | Missing or invalid API key | `{ "error": "Unauthorized" }` | | `404` | No tool with that id in your workspace | `{ "error": "Tool not found" }` | # Delete Webhook Source: https://docs.tuco.ai/api-reference/endpoint/delete-webhook DELETE /api/webhooks/{id} Permanently delete a webhook. REST endpoint in the Tuco AI iMessage API — bearer-token auth, JSON request/response, full schema and code examples. > [!WARNING] > > **The Try it panel runs against production** (`https://app.tuco.ai`) with the key you paste > into it. There is no sandbox — a request from this page permanently deletes a real webhook. Permanently delete a webhook. All future event deliveries to this endpoint stop immediately. ## Authentication ```bash theme={null} Authorization: Bearer tuco_xxxxxxxxxxxxx ``` *** ## Path parameters **id** `string` *required* Webhook ID. *** ## Example ```bash theme={null} curl -X DELETE "https://app.tuco.ai/api/webhooks/680a1b2c3d4e5f6789012345" \ -H "Authorization: Bearer tuco_xxxxxxxxxxxxx" ``` ```json 200 Response theme={null} { "success": true } ``` > [!TIP] > > If you just want to temporarily stop delivery, use [Update Webhook](/api-reference/endpoint/update-webhook) with `isActive: false` instead of deleting. *** ## Errors | Status | When | | - | - | | `401` | Invalid or missing API key | | `402` | Subscription past due | | `404` | Webhook not found in your workspace | # Workspace Email Preferences Source: https://docs.tuco.ai/api-reference/endpoint/email-preferences POST /api/email-preferences Read and change which Tuco notification emails one workspace sends, such as reply alerts and digests, using that workspace's own API key. > [!NOTE] > > Controls which Tuco emails go out for one workspace. Use the **workspace** API key > (`tuco_…`). Agencies changing this across many workspaces at once should use > [Agency Email Preferences](/api-reference/endpoint/agency-email-preferences) instead. ## Endpoint * **Method**: `POST` to change, `GET` to read * **Path**: `/api/email-preferences` * **Auth**: `Authorization: Bearer tuco_xxxxxxxxxxxxx` ## Email types | Type | Covers | | - | - | | `campaign` | Retained for compatibility | | `reply` | Inbound reply alerts. Also carries `mode` | | `billing` | Invoices, payment failures, plan changes | | `system_error` | Platform errors affecting your workspace | | `line_health` | Retained for compatibility — line-down emails are controlled by each line's **Line Down Notifications** toggle, not here | | `line_reschedule` | **Line Health — Reschedule Notifications.** At most one email a day when a line hits its daily new-contact (or total message) limit and the remaining sends are rescheduled to the next morning. Nothing is dropped either way. On by default | `reply.mode` is one of `all`, `positive_only`, `debounce_5min` (default) or `daily_digest`. ## Read ```bash theme={null} curl https://app.tuco.ai/api/email-preferences \ -H "Authorization: Bearer tuco_xxxxxxxxxxxxx" ``` ```json theme={null} { "success": true, "preferences": { "line_health": { "enabled": true }, "campaign": { "enabled": true }, "reply": { "enabled": true, "mode": "debounce_5min" }, "billing": { "enabled": true }, "system_error": { "enabled": true }, "line_reschedule": { "enabled": true } } } ``` ## Change Send only what you want to change — everything else is preserved. ```bash theme={null} curl https://app.tuco.ai/api/email-preferences \ -H "Authorization: Bearer tuco_xxxxxxxxxxxxx" \ -H "Content-Type: application/json" \ -d '{ "preferences": { "billing": { "enabled": false }, "reply": { "enabled": true, "mode": "daily_digest" } } }' ``` The response is the full merged preference object. ## Error responses | Status | When | | - | - | | `400` | `preferences` missing or not an object, an unknown email type, or an invalid `reply.mode` | | `401` | Missing or invalid key | | `403` | An agency key (`tucoagency_…`) was used — this is a per-workspace setting | # Enroll Lead (instruction bots) Source: https://docs.tuco.ai/api-reference/endpoint/enroll-lead POST /api/instructions/{id}/enroll Enrol a lead into an instruction bot. Also answers on /api/goal-bots/{id}/enroll. Instruction bots are being retired — goal bots fire on tags instead. > [!WARNING] > > **Instruction bots are being retired.** They are the older stage-based engine: a lead is > *enrolled* into one and walks a sequence of stages. The engine that replaced them — > [goal bots](/api-reference/endpoint/list-goal-bots) — has no stages and no enrolment: you tag a > lead and the bot handles their replies. > > Build new work on goal bots. These endpoints stay up for integrations already using them. Puts a lead into an instruction bot at its first stage. Also answers on `POST /api/goal-bots/{id}/enroll` — that path stayed pointed at the instruction engine when the rest of `/api/goal-bots` moved, because published integrations depend on it. > [!NOTE] > > **Goal bots do not use this endpoint.** To put a lead in front of a goal bot, add its trigger tag > with [`PATCH /api/leads/{id}`](/api-reference/endpoint/update-lead). ## Authentication Pass your workspace API key as a Bearer token, or use a Clerk session token. ```bash theme={null} Authorization: Bearer tuco_xxxxxxxxxxxxx ``` *** ## Path parameter **id** `string` *required* The **instruction** id from [`GET /api/instructions`](/api-reference/endpoint/list-instruction-bots). Not a goal bot id — the two live in different collections. A malformed id returns `400 Invalid instruction ID`. *** ## Request body **leadId** `string` *required* The lead to enrol. Missing or malformed returns `400 Valid leadId is required`. *** ## Example ```bash theme={null} curl -X POST "https://app.tuco.ai/api/instructions/6a970c3429603484fb08b211/enroll" \ -H "Authorization: Bearer tuco_xxxxxxxxxxxxx" \ -H "Content-Type: application/json" \ -d '{ "leadId": "6ac3ea0d71adb32c88d56219" }' ``` ### Success (`200 OK`) ```json theme={null} { "success": true, "message": "Lead enrolled in instruction" } ``` The lead is set to the instruction's **first stage**, its turn counter is reset, and the instruction's `stats.totalEnrolled` and `stats.inProgress` both increment. *** ## Rules > [accordion] The instruction must be active > > A `draft` or `paused` instruction returns `400 Instruction is not active`. > [accordion] A lead can be in only one instruction at a time > > Enrolling a lead that is already enrolled anywhere returns > `400 Lead is already enrolled in an instruction`. Unenrol first with > [`DELETE`](/api-reference/endpoint/unenroll-lead). > [accordion] The instruction needs at least one stage > > An instruction with no stages returns `400 Instruction has no steps`. *** ## Errors | Status | When | Body | | - | - | - | | `400` | Malformed `{id}` | `{ "error": "Invalid instruction ID" }` | | `400` | `leadId` missing or malformed | `{ "error": "Valid leadId is required" }` | | `400` | Instruction is not `active` | `{ "error": "Instruction is not active" }` | | `400` | Lead already enrolled somewhere | `{ "error": "Lead is already enrolled in an instruction" }` | | `400` | Instruction has no stages | `{ "error": "Instruction has no steps" }` | | `401` | Missing or invalid API key | `{ "error": "Unauthorized" }` | | `404` | Instruction not in your workspace | `{ "error": "Instruction not found" }` | | `404` | Lead not in your workspace | `{ "error": "Lead not found" }` | # Read Fallback SMS Config Source: https://docs.tuco.ai/api-reference/endpoint/fallback-config GET /api/workspace/fallback-config Read where backup SMS is sent when iMessage fails, including whether your own Telnyx credentials are stored. Bearer-token auth, JSON response. > [!NOTE] > > Everything on the **Settings → Fallbacks** page is available here, so backup SMS can be set up > entirely over the API without opening the dashboard. > > A backup text goes out when iMessage cannot deliver, for two separate reasons: the send failed > technically, or the recipient has no iMessage. Both use the same destination. Reads the workspace's current fallback setup. To change it, use [`PATCH /api/workspace/fallback-config`](/api-reference/endpoint/update-fallback-config). ## Authentication Pass your workspace API key as a Bearer token, or use a Clerk session token. ```bash theme={null} Authorization: Bearer tuco_xxxxxxxxxxxxx ``` There are no query parameters — the workspace comes from your key. *** ## Example ```bash theme={null} curl "https://app.tuco.ai/api/workspace/fallback-config" \ -H "Authorization: Bearer tuco_xxxxxxxxxxxxx" ``` ### Success (`200 OK`) ```json theme={null} { "fallbackDestination": "telnyx", "telnyxFromNumber": "+13055550142", "telnyxUseOwnAccount": true, "telnyxApiKeyAvailable": true, "telnyxHasOwnApiKey": true, "telnyxHasOwnPublicKey": true, "sendFallbackSmsOnFailed": true, "dailyLimitOverflow": "reschedule", "twilioEncryptionAvailable": true, "secretsEncryptionAvailable": true, "customWebhookEnabled": false } ``` > [!WARNING] > > **Credentials are never returned.** `telnyxHasOwnApiKey` and `telnyxHasOwnPublicKey` say only > whether a key is stored — the key itself is write-only and cannot be read back. ## Response **fallbackDestination** `string` `none`, `ghl`, `twilio` or `telnyx`. `none` means no backup text will ever go out. **telnyxFromNumber** `string` E.164 number backup texts are sent from, and where replies come back to. **telnyxUseOwnAccount** `boolean` `true` when sending on your own Telnyx account rather than Tuco's. **telnyxHasOwnApiKey** `boolean` Whether your own API key is stored. **telnyxHasOwnPublicKey** `boolean` Whether your own public key is stored. Without it, replies from leads are rejected as unverified. **telnyxApiKeyAvailable** `boolean` Whether a usable key exists at all — yours or Tuco's. **sendFallbackSmsOnFailed** `boolean` Whether a technical send failure also triggers a backup text, not only "no iMessage". **dailyLimitOverflow** `string` `reschedule` or `fallback` — what happens when a line hits its daily cap. **customWebhookEnabled** `boolean` Whether a custom webhook destination is configured. **twilioEncryptionAvailable** `boolean` Whether credential encryption is available on this workspace. **secretsEncryptionAvailable** `boolean` Same, for the shared secrets store. *** ## Errors | Status | When | Body | | - | - | - | | `400` | Key has no active workspace | `{ "error": "No active workspace" }` | | `401` | Missing or invalid API key | `{ "error": "Unauthorized" }` | # Get & Search Leads Source: https://docs.tuco.ai/api-reference/endpoint/get GET /api/leads Retrieve, list, and search leads in a workspace — find a lead by name, email, phone, or company, fetch one by id, or page through them all. Bearer-token auth. ## Endpoint * **Method**: `GET` * **Path**: `/api/leads` Returns leads in the active workspace, matching what you see in the Tuco UI. This is the endpoint a CRM built on Tuco uses to **look up a contact** (by phone, email, name, or company) and to **sync the lead list**. *** ## Query Parameters * `id` (`string`, optional) – return a **single lead** by its `_id` (24-char ObjectId). When present, the other filters are ignored. * `search` (`string`, optional) – case‑insensitive match across **first name, last name, email, phone, and company name**. This is how you find a specific lead — pass a phone number or email to locate one contact. * `listId` (`string`, optional) – restrict to a specific Tuco list. * `page` (`number`, optional, default `1`) – page number. * `limit` (`number`, optional, default `50`, max `50`) – page size. ### Find a lead by phone or email ```bash theme={null} # by phone curl "https://app.tuco.ai/api/leads?search=%2B12025551234&limit=1" \ -H "Authorization: Bearer tuco_xxxxxxxxxxxxx" # by email curl "https://app.tuco.ai/api/leads?search=john@example.com&limit=1" \ -H "Authorization: Bearer tuco_xxxxxxxxxxxxx" ``` ### Fetch one lead by id, or page through a list ```bash theme={null} GET /api/leads?id=667f1f77bcf86cd799439012 GET /api/leads?listId=507f1f77bcf86cd799439011&search=john&page=1&limit=50 Authorization: Bearer tuco_xxxxxxxxxxxxx ``` *** ## Response ```json theme={null} { "leads": [ { "_id": "667f1f77bcf86cd799439012", "firstName": "John", "lastName": "Doe", "email": "john@example.com", "phone": "+12025551234", "companyName": "Acme Corp", "jobTitle": "CEO", "listId": "507f1f77bcf86cd799439011", "workspaceId": "org_123", "createdAt": "2025-10-14T10:30:00Z", "updatedAt": "2025-10-14T10:30:00Z" } ], "lists": [ { "_id": "507f1f77bcf86cd799439011", "name": "Prospects – October", "workspaceId": "org_123" } ], "pagination": { "page": 1, "limit": 50, "totalCount": 1, "totalPages": 1 } } ``` No hidden changes are applied to your data by reading; this endpoint is read‑only from your point of view. Errors such as missing auth (`401`) or invalid query parameters (`400`) are returned with clear JSON messages. # Get Goal Bot Source: https://docs.tuco.ai/api-reference/endpoint/get-goal-bot GET /api/goal-bots/{id} Fetch a Tuco AI goal bot by ID — returns goal definition, persona, knowledge base, approval mode, active enrollment count, and config metadata. > [!NOTE] > > **Goal bots and task agents are the same object.** The two engines merged; `/api/goal-bots` > and `/api/tasks` are aliases over one collection and return identical bodies. Every response > carries both `goalBot` and `taskAgent` (or `goalBots` and `taskAgents`) so integrations written > against either name keep working. > > The older stage-based engine moved to [`/api/instructions`](/api-reference/endpoint/list-instruction-bots) > and is being retired. Reads one bot by id. The lookup is scoped to your workspace, so an id from another workspace returns `404` rather than leaking anything. ## Authentication Pass your workspace API key as a Bearer token, or use a Clerk session token. ```bash theme={null} Authorization: Bearer tuco_xxxxxxxxxxxxx ``` *** ## Path parameter **id** `string` *required* The bot id — `_id` from [`GET /api/goal-bots`](/api-reference/endpoint/list-goal-bots) or `goalBot._id` from [create](/api-reference/endpoint/create-goal-bot). A malformed id returns `400 Invalid id`. *** ## Example ```bash theme={null} curl "https://app.tuco.ai/api/goal-bots/6aa9813105bb2cbf5931ac1f" \ -H "Authorization: Bearer tuco_xxxxxxxxxxxxx" ``` ### Success (`200 OK`) ```json theme={null} { "goalBot": { "_id": "6aa9813105bb2cbf5931ac1f", "name": "Auto Replies", "prompt": "You're Raj from Tuco...", "mode": "autopilot", "status": "active", "connector": "calendly", "includeTags": [], "excludeTags": [], "kbRetrieval": "always", "canAsk": true, "maxTurns": 8, "typingIndicator": true, "writeTagToCrm": false, "isDefault": true, "createdAt": "2026-09-03T18:11:29.004Z", "updatedAt": "2026-10-02T09:40:12.551Z" }, "taskAgent": { /* identical object */ } } ``` ## Response **goalBot** `object` The bot. **Goal bot fields** **\_id** `string` Bot id. Use it on every `{id}` route. **name** `string` Display name. **prompt** `string` The instructions the model runs on. **mode** `string` `autopilot`, `copilot`, `manual`, or the legacy alias `draft`. **status** `string` `active` or `paused`. **connector** `string` `calendly` or `ghl_calendar`. **includeTags** `string[]` Tags that wake the bot. **excludeTags** `string[]` Tags that keep it out. **kbRetrieval** `string` `always` or `auto`. **canAsk** `boolean` Whether the bot may ask follow-up questions. **maxTurns** `number` Reply cap per conversation. **typingIndicator** `boolean` Whether it sends a typing signal before replying. **writeTagToCrm** `boolean` Whether `onDoneTag` is pushed to the connected CRM. **onDoneTag** `string` Tag applied when the bot finishes. **allowedToolIds** `string[]` Ids from [`GET /api/campaign-tools`](/api-reference/endpoint/list-tools) the bot may call. **collectFields** `string[]` Fields the bot tries to collect. **isDefault** `boolean` `true` for the built-in **Auto Replies** bot, which cannot be deleted. **createdAt** `string` ISO 8601 timestamp. **updatedAt** `string` ISO 8601 timestamp. **taskAgent** `object` The same object under the pre-rename key. *** ## Errors | Status | When | Body | | - | - | - | | `400` | Malformed `{id}` | `{{ "error": "Invalid id" }}` | | `400` | Key has no active workspace | `{{ "error": "No active workspace" }}` | | `401` | Missing or invalid API key | `{{ "error": "Unauthorized" }}` | | `404` | No bot with that id in your workspace | `{{ "error": "Not found" }}` | # Get Lead Source: https://docs.tuco.ai/api-reference/endpoint/get-lead GET /api/leads/{id} Read a single lead in your Tuco workspace by id. Lookups are workspace-scoped, so ids from other workspaces return 404. Find ids via GET /api/leads. Reads one lead by id. The lookup is scoped to your workspace, so an id from another workspace returns `404` rather than leaking anything. > [!TIP] > > Don't have the id? [`GET /api/leads?search=…`](/api-reference/endpoint/get) finds a lead by > phone, email, name or company. Search by phone in E.164 and URL-encode the `+` as `%2B`. ## Authentication Pass your workspace API key as a Bearer token, or use a Clerk session token. ```bash theme={null} Authorization: Bearer tuco_xxxxxxxxxxxxx ``` *** ## Path parameter **id** `string` *required* The lead id — `leadId` from [`POST /api/leads`](/api-reference/endpoint/create), or `_id` from [`GET /api/leads`](/api-reference/endpoint/get). A malformed id returns `400 Invalid lead id`. *** ## Example ```bash theme={null} curl "https://app.tuco.ai/api/leads/6ac3ea0d71adb32c88d56219" \ -H "Authorization: Bearer tuco_xxxxxxxxxxxxx" ``` ### Success (`200 OK`) ```json theme={null} { "lead": { "_id": "6ac3ea0d71adb32c88d56219", "firstName": "Jane", "lastName": "Doe", "phone": "+14152004145", "email": "jane@example.com", "companyName": "Acme Corp", "notes": "Warm intro from Sarah", "tags": ["demo-requested"], "customFields": { "industry": "Technology" }, "listId": "69f4773ce651a48f743b77f9", "source": "api", "integrationIds": { "ghlRecordId": null, "hubspotRecordId": null }, "createdAt": "2026-10-05T18:18:50.277Z", "updatedAt": "2026-10-05T18:48:02.917Z" } } ``` ## Response **lead** `object` The lead. Only these fields are returned — enrolment state and internal bookkeeping are not exposed. **Lead fields** **\_id** `string` Lead id. **firstName** `string` First name. **lastName** `string` Last name. **phone** `string` Phone in E.164. **Read-only here** — set it at creation with [`POST /api/leads`](/api-reference/endpoint/create). **email** `string` Email address. **companyName** `string` Company. **notes** `string` Free-text notes. Your bots read this — see [Update Lead](/api-reference/endpoint/update-lead). **tags** `string[]` Tags on the lead. These are what fire your bots. **customFields** `object` Free-form key/value data. **source** `string` Where the lead came from, e.g. `api`, `gohighlevel`. **listId** `string` List that owns the lead. **integrationIds** `object` Linked CRM record ids (`ghlRecordId`, `hubspotRecordId`, …). **createdAt** `string` ISO 8601 timestamp. **updatedAt** `string` ISO 8601 timestamp. *** ## Errors | Status | When | Body | | - | - | - | | `400` | Malformed `{id}` | `{ "error": "Invalid lead id" }` | | `400` | Key has no active workspace | `{ "error": "No active workspace" }` | | `401` | Missing or invalid API key | `{ "error": "Unauthorized" }` | | `404` | No lead with that id in your workspace | `{ "error": "Lead not found" }` | # Get Line Request Source: https://docs.tuco.ai/api-reference/endpoint/get-line-request GET /api/line-requests/{id} Fetch the current status of a line request. REST endpoint in the Tuco AI iMessage API — bearer-token auth, JSON request/response, full schema and code examples. > [!NOTE] > > Use this endpoint to poll a specific line request after creation. It is the source of truth for whether the request is still waiting for payment, already provisioning, active, failed, or canceled. > [!NOTE] > > **Any line id in your workspace works here**, not only ids returned by `POST /api/line-requests`. A line created in the dashboard resolves the same way — you get its current `provisioningStatus` and the full line object. > > The write actions in [`POST /api/line-requests/{id}`](/api-reference/endpoint/manage-line-request) are different: `cancel` and `payment_link` act only on API-created requests awaiting payment, and return `404 Line request not found` for anything else. ## When To Use This Endpoint Call this endpoint any time your integration wants to answer one of these questions: * Did the user already pay? * Has provisioning started yet? * Is the line active? * Was the request canceled or did it fail? This is the simplest endpoint to poll after `POST /api/line-requests`. ## Authentication Pass your workspace API key as a Bearer token, or use a Clerk session token. ```bash theme={null} Authorization: Bearer tuco_xxxxxxxxxxxxx ``` *** ## Path parameter **id** `string` *required* The line request id returned by `POST /api/line-requests` — it is the `line._id` value in that response. A line request is not a separate record: it is the line itself. The request id and the line id are therefore the same value, which is why any line id from [`GET /api/lines/by-user`](/api-reference/endpoint/get-lines) also resolves here. A `404` means the id is not a line in your workspace; a malformed id returns `400 Invalid line request id`. *** ## Example ```bash theme={null} curl "https://app.tuco.ai/api/line-requests/6a09279daa903300e2530b0f" \ -H "Authorization: Bearer tuco_xxxxxxxxxxxxx" ``` ### Success (`200 OK`) ```json theme={null} { "success": true, "status": "provisioning", "paymentStatus": "paid", "paymentRequired": false, "line": { "_id": "6a09279daa903300e2530b0f", "firstName": "Support", "lastName": "Email 2", "channelType": "email", "lineType": "purchased", "provisioningStatus": "provisioning", "paymentStatus": "paid" } } ``` *** ## Status behavior | `status` | Meaning | | - | - | | `awaiting_payment` | Invoice is still unpaid | | `provisioning` | Payment is complete or not required, and Tuco is provisioning the line | | `active` | Line is ready to use | | `failed` | Provisioning did not succeed | | `canceled` | The pending request was canceled | When possible, Tuco also reconciles a stuck `awaiting_payment` request against the latest subscription state while reading this endpoint. ### Practical meaning of each status * `awaiting_payment` The request exists, but the invoice is still unpaid or billing has not been reconciled yet. * `provisioning` Payment is done or was never needed, and Tuco is now setting the line up. * `active` The line is ready to use in normal message flows. * `failed` Provisioning did not complete. At that point the request needs review or a retry path outside this endpoint. * `canceled` The pending request was intentionally canceled before completion. ### Typical polling behavior Most clients poll after: 1. creating a paid request 2. showing the hosted invoice to the user 3. waiting for the request to move from `awaiting_payment` to `provisioning` After that, the same endpoint can still be used until the line becomes `active`. *** ## Error responses | Status | When | Body | | - | - | - | | `400` | Invalid line request id | `{ "error": "Invalid line request id" }` | | `401` | Missing or invalid API key / session | `{ "error": "Unauthorized" }` | | `404` | Request not found in your workspace | `{ "error": "Line request not found" }` | # Get All Lines Source: https://docs.tuco.ai/api-reference/endpoint/get-lines GET /api/lines/by-user List all iMessage/SMS lines for the authenticated workspace. REST endpoint in the Tuco AI iMessage API — bearer-token auth, JSON request/response, full schema. > [!NOTE] > > Returns every line for the workspace with usage (new conversations and total messages for today) and health status. Use the line `_id` as `fromLineId` when sending messages, or omit it for round-robin. ## Endpoint * **Method**: `GET` * **Path**: `/api/lines/by-user` * **Auth**: `Authorization: Bearer tuco_xxxxxxxxxxxxx` ## Example request ```bash theme={null} GET https://app.tuco.ai/api/lines/by-user Authorization: Bearer tuco_xxxxxxxxxxxxx ``` ## Success response (200) ```json theme={null} { "lines": [ { "_id": "699f704bc405fae6ca299a08", "workspaceId": "org_3ABCDbdGyF6w99hikyVN4cmo6H0", "phone": "+16465550100", "email": "john@example.com", "firstName": "Lindsey", "lastName": "Rodriguez", "profileImageUrl": "https://cdn.example.com/lindsey.png", "isActive": true, "provisioningStatus": "active", "lineType": "byon", "dailyNewConversationsLimit": 20, "dailyTotalMessagesLimit": 50, "usage": { "date": "2026-03-01", "newConversationsCount": 4, "totalMessagesCount": 11 }, "healthCheck": { "status": "healthy", "lastCheckedAt": "2026-03-01T20:52:00.097Z" }, "createdAt": "2026-02-25T21:57:31.276Z", "updatedAt": "2026-03-01T20:52:04.622Z" } ] } ``` ## Profile fields | Field | Type | Notes | | - | - | - | | `firstName` | string | Line's first name. | | `lastName` | string | Line's last name. | | `profileImageUrl` | string \| null | Public URL of the line's profile photo, or `null` if none is set. This field is part of the stable response. | ## Calling fields | Field | Type | Notes | | - | - | - | | `callRecordingDisclosure` | boolean | `true` when the line plays a "this call may be recorded" notice on its calls. Absent or `false` = off. | | `callRecordingDisclosureMessage` | string | Your custom notice text. Absent = the default notice. | To change any of these, use [Update a Line](/api-reference/endpoint/update-line). ## Error responses | Status | When | Body | | - | - | - | | `400` | No active workspace | `{ "error": "No active workspace" }` | | `401` | Missing or invalid API key | `{ "error": "Unauthorized" }` | | `500` | Server error | `{ "error": "Internal server error" }` | *** Use the **Try it** panel to run this request interactively. # Get Message History Source: https://docs.tuco.ai/api-reference/endpoint/get-messages GET /api/messages Read the full conversation with a lead in Tuco: inbound and outbound messages together, newest first, paginated. Filter by leadId for one thread. > [!NOTE] > > Pair this with [Get call recordings](/api-reference/endpoint/get-recordings) to > assemble a complete history for a lead: texts here, calls there. ## Overview Returns messages in your workspace, newest first. Filter by `leadId` to read the **whole conversation with one lead** — inbound replies and outbound sends in the same list. ## Authentication Pass your workspace API key as a Bearer token. ```bash theme={null} Authorization: Bearer tuco_xxxxxxxxxxxxx ``` *** ## Making a request ```bash theme={null} curl "https://app.tuco.ai/api/messages?leadId=6a4ed2d5dec1b2d01a6f7656&limit=50" \ -H "Authorization: Bearer tuco_your_key" ``` ### Query parameters **leadId** `string` Only messages for this lead — this is how you read a single conversation. 24-character ObjectId hex. **lineId** `string` Only messages sent from this Tuco line. 24-character ObjectId hex. **upstreamCorrelationId** `string` Match the `correlationId` returned in a [drip](/api-reference/drip) `202` ack. Useful for confirming a queued drip became a real message. **page** `number` Page number, 1-based. Default `1`. **limit** `number` Messages per page. Default `50`. *** ## Looking a conversation up by phone number > [!WARNING] > > This endpoint has **no phone-number filter**. `leadId` is the only way to scope to > one conversation. To start from a phone number, resolve the lead first, then pass its id: ```bash theme={null} # 1. find the lead curl "https://app.tuco.ai/api/leads?search=%2B13025550123" \ -H "Authorization: Bearer tuco_your_key" # 2. read the conversation curl "https://app.tuco.ai/api/messages?leadId=THE_LEAD_ID" \ -H "Authorization: Bearer tuco_your_key" ``` If you only need the lead's **replies** and not the full thread, [Get replies](/api-reference/endpoint/get-replies) accepts `recipientPhone` directly and skips the lookup. *** ## Response ```json theme={null} { "messages": [ { "_id": "6a4ed2d5dec1b2d01a6f7656", "message": "Sounds good — Tuesday works.", "status": "delivered", "channelType": "imessage", "createdAt": "2026-09-17T15:28:41.632Z", "fromLine": { "_id": "6a4ed2d5dec1b2d01a6f7600", "firstName": "Main", "lastName": "Line", "phone": "+13025550999", "email": "line@example.com" }, "recipient": { "_id": "6a4ed2d5dec1b2d01a6f7601", "firstName": "Dana", "lastName": "Reed", "phone": "+13025550123", "email": "dana@example.com" }, "attachmentDownloadUrls": ["https://app.tuco.ai/api/attachments/crm-media/photo.jpg?u=...&sig=..."], "attachmentNames": ["photo.jpg"] } ], "pagination": { "page": 1, "limit": 50, "totalCount": 128, "totalPages": 3 } } ``` **messages** `array` Messages, newest first. **message fields** **\_id** `string` Message ID. **message** `string` Message body. Empty for attachment-only sends. **status** `string` Delivery status, e.g. `queued`, `scheduled`, `sent`, `delivered`, `failed`, `cancelled`. **channelType** `string` How it was sent — e.g. `imessage`, `sms`, `email`. **createdAt** `string` When the message was created. **fromLine** `object` The Tuco line it was sent from (`_id`, `firstName`, `lastName`, `phone`, `email`). `null` if the line has since been removed. **recipient** `object` The lead (`_id`, `firstName`, `lastName`, `phone`, `email`). `null` if the lead has since been removed. **attachmentDownloadUrls** `array` Signed, fetchable URLs for the message's attachments — **present only when the message has attachments**, max 5. **attachmentNames** `array` Filenames matching `attachmentDownloadUrls`. Present only when the message has attachments. > [!NOTE] > > The **full stored message document** is returned, so you will see fields beyond those > listed above — e.g. `attachmentUrls`, `correlationId`. The fields listed > are the ones this endpoint guarantees or adds. **pagination** `object` **pagination fields** **page** `number` Current page. **limit** `number` Page size used. **totalCount** `number` Total matching messages. **totalPages** `number` Total pages available. > [!WARNING] > > A message's raw `attachmentUrls` point at private storage and return **403** to an API > key. Use `attachmentDownloadUrls` instead — those are signed and fetchable. > [!NOTE] > > You only ever see messages in your own workspace. The API key you authenticate with > determines the workspace; there is no parameter to query another one. *** ## Errors | HTTP | Meaning | | - | - | | 401 | Missing or invalid API key | | 400 | No active workspace for this key | | 500 | Unexpected server error | # Get Call Recordings Endpoint Source: https://docs.tuco.ai/api-reference/endpoint/get-recordings GET /api/voice/recordings Fetch a lead's calls by phone number, newest first, with timing details and a recording download URL. Get every recording or only the latest one. > [!NOTE] > > This endpoint is in **beta**. The interface is stable enough to build on; we may add fields as it matures. ## Overview Pull the calls placed to a given number in your workspace, newest first, each with its timing details and a recording download URL. Use it to fetch **all** recordings for a lead or just the **latest** one, straight into your own system. Recording is **on by default** for every workspace — there is nothing to enable. Every outbound call that **connects** is recorded automatically, and the audio is available a few seconds after the call ends. To list every recording in your workspace rather than the calls to one lead, see [List recordings & uploads](/api-reference/endpoint/list-recordings). *** ## Making a request * **Method**: `GET` * **URL**: `https://app.tuco.ai/api/voice/recordings` * **Headers**: `Authorization: Bearer tuco_...` ```bash theme={null} curl "https://app.tuco.ai/api/voice/recordings?number=%2B13025550123&latest=true" \ -H "Authorization: Bearer tuco_your_key" ``` ### Query parameters **number** `string` *required* The lead's phone number, E.164 (e.g. `+13025550123`). **URL-encode the `+` as `%2B`.** In a query string a raw `+` means a space, and calls are matched on the exact E.164 string — so `?number=+13025550123` looks up `13025550123`, matches nothing, and returns `200` with `"count": 0`. The **Try it** panel encodes this for you; hand-written requests must do it themselves. **to** `string` Alias for `number`. Accepted interchangeably; supply one or the other. **latest** `boolean` Return only the most recent call to that number. **withRecordingOnly** `boolean` Return only calls that have a recording URL. **limit** `number` Max calls to return. Default `20`, max `100`. Ignored when `latest=true`. *** ## Response Calls are returned newest first. Each entry includes timing details and the recording download URL (recordings resolve after a call ends). ```json theme={null} { "number": "+13025550123", "count": 2, "calls": [ { "callId": "6a4ed2d5dec1b2d01a6f7656", "from": "+13025550999", "to": "+13025550123", "agent": "+13025550456", "surface": "api", "status": "billed", "requestedAt": "2026-07-09T00:12:03.000Z", "answeredAt": "2026-07-09T00:12:19.000Z", "endedAt": "2026-07-09T00:13:01.000Z", "durationSec": 42, "billedSec": 42, "billedCents": 1, "hangupCause": "normal_clearing", "recordingUrl": "https://.../recordings/6a4ed2d5....mp3" } ] } ``` **number** `string` The number you queried. **count** `number` Number of calls returned. **calls** `array` The calls, newest first. **call fields** **callId** `string` Call record ID. **from** `string` Caller ID the lead saw (your Tuco number). **to** `string` The number called. **agent** `string` Your rep's number (API calls only). **surface** `string` Where the call was placed from — `api`, `tuco_unibox`, `tuco_leads`, `ghl_menu`, `pd_dialer`, `hubspot_ext` or `direct_url`. **status** `string` `requested` · `ringing` · `answered` · `billed` · `failed`. **requestedAt** `string` When the call was created. **answeredAt** `string` When it connected. **endedAt** `string` When it ended. **durationSec** `number` Talk time in seconds. **billedSec** `number` Billed seconds. **billedCents** `number` Internal cost for the call, in cents. **hangupCause** `string` Why the call ended. **recordingUrl** `string` Signed download URL for the recording audio, or `null`. See [Recording URLs expire](#recording-urls-expire). > [!NOTE] > > You only ever see calls in your own workspace. Recordings resolve a few seconds after > a call ends; a `null` `recordingUrl` on a live or very recent call is expected. *** ## Recording URLs expire > [!WARNING] > > `recordingUrl` is a **signed link that expires 30 days after you fetch it**. Do not > store the URL — store the `callId` and call this endpoint again when you need the > audio. A saved URL will start returning an error once it lapses. Each call returns a fresh link, so re-requesting is the supported way to get a working URL. The audio itself is kept indefinitely; only the link is time-limited. ## When a recording exists A recording only exists for a call that **connected**. Specifically: * Recording starts the moment the call is **answered**, so unanswered, busy and failed calls have no audio and return `recordingUrl: null`. * A call answered and dropped within a second or two may also have no audio — the recording had not started yet. * Audio is **MP3, mono**. Both sides of the conversation are mixed into a single channel, so the format is suited to playback and transcription, but not to separating the speakers. ## Automatic CRM sync If your workspace has **HubSpot** connected, you do not need this endpoint to get recordings into your CRM. When a call ends, Tuco writes a note to that contact's HubSpot timeline containing a play link, timestamped to the time of the call. Nothing to configure. Use this endpoint when you want the audio in **your own** system — a data warehouse, a transcription pipeline, or a CRM other than HubSpot. *** ## Errors | HTTP | `code` | Meaning | | - | - | - | | 401 | `UNAUTHORIZED` | Missing or invalid API key | | 400 | `MISSING_NUMBER` | `number` (the lead phone number) not provided | | 500 | `INTERNAL_ERROR` | Unexpected server error | # Check Replies Source: https://docs.tuco.ai/api-reference/endpoint/get-replies GET /api/replies Get replies for a lead — who replied, what they said, and the conversation context. REST endpoint in the Tuco AI iMessage API — bearer-token auth. > [!NOTE] > > Use this endpoint to check if a specific lead has replied, or to list all leads who replied (optionally filtered by line or date). Returns the reply text, up to 10 recent replies from the lead, and up to 10 outbound messages you sent them. > > When a lead replies with a **photo or file**, the row (and each `recentReplies` entry) carries `attachmentDownloadUrls` — public, signed URLs you can `GET` directly to download the image/file bytes, no auth header needed. A reply can include **many** attachments; for a large photo burst the list fills in over a minute or two as background ingestion completes, so poll again if you need the complete set. See [Downloading inbound attachments](#downloading-inbound-attachments). ## Authentication ```bash theme={null} Authorization: Bearer tuco_xxxxxxxxxxxxx ``` ## Query parameters **leadId** `string` Replies from this lead only (valid ObjectId; returns 404 if lead not found). **recipientEmail** `string` Filter by reply sender email. **recipientPhone** `string` Filter by reply sender phone (E.164 or normalized). **lineId** `string` Restrict to replies received on this Tuco line (24-char ObjectId hex). Returns `400` if malformed. **dateFrom** `string` Inclusive ISO 8601 UTC lower bound on the reply timestamp (e.g. `2026-06-01T00:00:00Z`). Returns `400` if unparseable or greater than `dateTo`. **dateTo** `string` Inclusive ISO 8601 UTC upper bound on the reply timestamp. **page** `number` (default: 1) Page number. **limit** `number` (default: 50) Results per page (max 100). *** ## Examples ```bash By phone number theme={null} curl "https://app.tuco.ai/api/replies?recipientPhone=%2B14422646782&limit=10" \ -H "Authorization: Bearer tuco_xxxxxxxxxxxxx" ``` ```bash By lead ID theme={null} curl "https://app.tuco.ai/api/replies?leadId=69b2c41d352a78479d2c623b" \ -H "Authorization: Bearer tuco_xxxxxxxxxxxxx" ``` ```bash By email theme={null} curl "https://app.tuco.ai/api/replies?recipientEmail=john%40example.com" \ -H "Authorization: Bearer tuco_xxxxxxxxxxxxx" ``` ```bash By line + date window theme={null} curl "https://app.tuco.ai/api/replies?lineId=60d5ec49e3a8a0001f9b9999&dateFrom=2026-06-01T00:00:00Z&dateTo=2026-06-10T23:59:59Z&page=1&limit=100" \ -H "Authorization: Bearer tuco_xxxxxxxxxxxxx" ``` *** ## Success response (200) ```json theme={null} { "replies": [ { "leadId": "69b2c41d352a78479d2c623b", "messageId": "69b340dd6dae1d942ece4d09", "message": "Stop", "respondedAtUtc": "2026-03-12T22:40:29.174Z", "recipientPhone": "+919876543210", "recipientEmail": "jane@example.com", "name": "Jane Doe", "hasReplied": false, "hasEverReplied": true, "attachmentDownloadUrls": [ "https://app.tuco.ai/api/attachments/crm-media/IMG_1380.jpeg?u=aHR0cHM...&exp=1786752000000&sig=Vh9k..." ], "attachmentNames": ["IMG_1380.jpeg"], "recentReplies": [ { "messageId": "69b340dd6dae1d942ece4d09", "message": "Stop", "receivedAtUtc": "2026-03-12T22:40:29.174Z" }, { "messageId": "69b33fdd6dae1d942ece4d08", "message": "Here's the photo you asked for", "receivedAtUtc": "2026-03-12T21:15:00.000Z", "attachmentDownloadUrls": [ "https://app.tuco.ai/api/attachments/crm-media/IMG_1380.jpeg?u=aHR0cHM...&exp=1786752000000&sig=Vh9k..." ], "attachmentNames": ["IMG_1380.jpeg"] } ], "parentMessages": [ { "messageId": "69b344bc6dae1d942ece4d0e", "message": "Here's your document.", "sentAtUtc": "2026-03-12T22:57:02.892Z", "batchId": null, "stepIndex": null } ] } ], "total": 1, "page": 1, "limit": 50, "totalPages": 1 } ``` ### Reply fields **leadId** `string` Lead who replied. **messageId** `string` ID of the most recent reply message. **message** `string` The reply text (e.g. "Stop", "Interested!", "Call me tomorrow"). **respondedAtUtc** `string` ISO 8601 timestamp of the most recent reply. **recipientPhone** `string` Lead's phone number. **recipientEmail** `string` Lead's email address. **name** `string` Lead's display name. **hasReplied** `boolean` `true` when the lead's newest inbound is newer than your newest outbound to them (no outbound on record → `true`). Any follow-up you send after their reply — including AI copilot auto-replies — flips it back to `false`. **hasEverReplied** `boolean` Always `true` for a returned row — leads who never replied have no row. Included so this endpoint and the GHL Check for Replies action expose the same field names; branch on it when an auto-responder makes `hasReplied` flip to `false` within seconds. **attachmentDownloadUrls** `string[]` Present only when the most recent reply included attachments. Public, signed, 30-day URLs — `GET` each one (no auth header) to download the actual image/file bytes, served with the correct `Content-Type`. Omitted for text-only replies. For a large photo burst this array may **grow** for a minute or two after the reply as background ingestion finishes — poll again to get the complete set. See [Downloading inbound attachments](#downloading-inbound-attachments). **attachmentNames** `string[]` Filenames aligned 1:1 with `attachmentDownloadUrls` (e.g. `["IMG_1380.jpeg"]`). Omitted for text-only replies. ### recentReplies (up to 10) All inbound replies from this lead, newest first. Gives you the full conversation context from their side. **recentReplies** `array` **Reply object** **messageId** `string` Reply message ID. **message** `string` Reply text (truncated to 200 chars). **receivedAtUtc** `string` When the reply was received (UTC ISO 8601). **attachmentDownloadUrls** `string[]` Present only when this reply included attachments. Public, signed download URLs for the image/file bytes (omitted otherwise). **attachmentNames** `string[]` Filenames aligned 1:1 with `attachmentDownloadUrls`. ### parentMessages (up to 10) Outbound messages you sent to this lead, newest first. Shows what you said before they replied. **parentMessages** `array` **Parent message object** **messageId** `string` Outbound message ID. **message** `string` Message text (truncated to 200 chars). **sentAtUtc** `string` When the message was sent (UTC ISO 8601). **batchId** `string` Batch ID if applicable. **stepIndex** `integer` Sequence step index if applicable. *** ## Error responses | Status | When | Body | | - | - | - | | `400` | Invalid `leadId` | `{ "error": "Invalid leadId" }` | | `400` | Invalid `lineId` (not a 24-char ObjectId hex) | `{ "error": "Invalid lineId" }` | | `400` | `dateFrom` / `dateTo` unparseable | `{ "error": "Invalid dateFrom" }` or `{ "error": "Invalid dateTo" }` | | `400` | `dateFrom > dateTo` | `{ "error": "dateFrom must be <= dateTo" }` | | `401` | Missing or invalid API key | `{ "error": "Unauthorized" }` | | `404` | `leadId` provided but lead not found | `{ "error": "Lead not found or access denied" }` | | `429` | Rate-limited (120 req/min per workspace) | `{ "error": "Rate limit exceeded" }` | | `500` | Server error | `{ "error": "Failed to fetch replies" }` | *** ## Downloading inbound attachments When a lead replies with a photo or file, Tuco stores the bytes in **private** blob storage. The raw storage URL is not directly fetchable — it returns `403`. Instead, every attachment-bearing reply exposes **`attachmentDownloadUrls`**: signed, 30-day proxy URLs that stream the real bytes with the correct `Content-Type`. You can fetch a download URL with **either** credential — pick whichever fits: > [card] Just the URL (signature) > > The URL already carries an HMAC signature (`&sig=…`), so **no header is needed**. Drop it into an ``, a re-hosting job, or `curl -O`. This is the simplest path. The signature is unforgeable and expires after 30 days. > [card] Your API key > > Prefer to pass a token? Send `Authorization: Bearer tuco_…`. Tuco verifies the key's workspace **owns** that attachment, so a key can only ever read its own workspace's files. Revocable by rotating the key. > [!WARNING] > > The signed URL grants read access to that one file for 30 days. Treat it like a capability: fetch and store the bytes in your own system rather than passing the URL around long-term. To fetch a fresh signed URL, just call `GET /api/replies` (or listen for the [`message.reply` webhook](/api-reference/endpoint/webhook)) again. ```bash Download every photo a lead sent theme={null} # 1) List the lead's replies and pull the download URLs + filenames curl -s "https://app.tuco.ai/api/replies?leadId=69b2c41d352a78479d2c623b" \ -H "Authorization: Bearer tuco_xxxxxxxxxxxxx" \ | jq -r '.replies[].recentReplies[] | select(.attachmentDownloadUrls != null) | .attachmentNames[] as $n | .attachmentDownloadUrls[] | [$n, .] | @tsv' \ | while IFS=$'\t' read -r name url; do # 2) Fetch the bytes — the signature in the URL is the credential, no header needed. # (Prefer your own token? add: -H "Authorization: Bearer tuco_xxxxxxxxxxxxx") curl -s "$url" -o "$name" echo "saved $name" done ``` The same `attachmentDownloadUrls` / `attachmentNames` fields are delivered in real time on the `message.reply` webhook and appear on inbound messages from [`GET /api/messages`](/api-reference/messages), so you can ingest photos push-style instead of polling. # Get Webhook Source: https://docs.tuco.ai/api-reference/endpoint/get-webhook GET /api/webhooks/{id} Get details for a single webhook. REST endpoint in the Tuco AI iMessage API — bearer-token auth, JSON request/response, full schema and code examples. Returns details for a single webhook. The secret is **never** returned. ## Authentication ```bash theme={null} Authorization: Bearer tuco_xxxxxxxxxxxxx ``` *** ## Path parameters **id** `string` *required* Webhook ID (returned when you created the webhook). *** ## Response **id** `string` Webhook ID **url** `string` Endpoint URL **events** `string[]` Subscribed event types **name** `string` Webhook name **description** `string | null` Optional description **isActive** `boolean` Whether the webhook is active **hasAuthHeader** `boolean` Whether a custom Authorization header is configured. The value itself is never returned. **lastTriggeredAt** `string | null` Last event sent (ISO UTC) **lastSuccessAt** `string | null` Last successful delivery (ISO UTC) **lastFailureAt** `string | null` Last failed delivery (ISO UTC) **failureCount** `number` Consecutive failure count **createdAt** `string` Creation timestamp **updatedAt** `string` Last update timestamp *** ## Example ```bash theme={null} curl "https://app.tuco.ai/api/webhooks/680a1b2c3d4e5f6789012345" \ -H "Authorization: Bearer tuco_xxxxxxxxxxxxx" ``` ```json 200 Response theme={null} { "id": "680a1b2c3d4e5f6789012345", "url": "https://example.com/webhooks/tuco", "events": ["message.sent", "message.failed", "message.reply"], "name": "Production webhook", "description": "Sends events to our CRM", "isActive": true, "hasAuthHeader": false, "lastTriggeredAt": "2026-04-12T10:30:00.000Z", "lastSuccessAt": "2026-04-12T10:30:00.000Z", "lastFailureAt": null, "failureCount": 0, "createdAt": "2026-03-01T00:00:00.000Z", "updatedAt": "2026-04-12T10:30:00.000Z" } ``` > [!TIP] > > Use `lastSuccessAt`, `lastFailureAt`, and `failureCount` to monitor your endpoint's health. > If `failureCount` is climbing, your endpoint might be down. # Get Webhook Delivery Source: https://docs.tuco.ai/api-reference/endpoint/get-webhook-delivery GET /api/webhooks/{id}/deliveries/{deliveryId} Get one webhook delivery in full: the exact request body and headers Tuco sent, your endpoint's response, and every attempt. Returns everything in the [list](/api-reference/endpoint/list-webhook-deliveries) entry, plus the full request and response. A custom `Authorization` header is shown as `[redacted]`; your webhook secret is never stored. ## Authentication ```bash theme={null} Authorization: Bearer tuco_xxxxxxxxxxxxx ``` ## Path parameters **id** `string` *required* Webhook ID. **deliveryId** `string` *required* Delivery `id` from the list. ## Response All list fields, plus: **method** `string` Always `POST`. **requestHeaders** `object` Headers sent, `Authorization` redacted. **requestBody** `object` The exact JSON body sent (what a replay re-sends). **responseBody** `string | null` First 4 KB of your endpoint's response. **attempts** `array` Each attempt: `attempt`, `at`, `responseStatus` or `error`, `latencyMs`. | Status | When | | - | - | | `200` | OK | | `401` | Missing or invalid API key | | `404` | Webhook or delivery not found in your workspace | ## Example ```bash theme={null} curl "https://app.tuco.ai/api/webhooks/680a1b2c3d4e5f6789012345/deliveries/6ad14a1e2f9c4b0012ab34cd" \ -H "Authorization: Bearer tuco_xxxxxxxxxxxxx" ``` # Check iMessage Availability (Single Lead) Source: https://docs.tuco.ai/api-reference/endpoint/lead-check-availability GET /api/leads/check-availability Check if a specific lead is reachable via iMessage. REST endpoint in the Tuco AI iMessage API — bearer-token auth, JSON request/response, full schema and code. Check iMessage availability for a single lead using their stored phone numbers and emails. Tuco checks every address on the lead (phone, email, altPhone1-3, altEmail1-3) and stops at the first one that is iMessage-capable. Updates the lead’s `availabilityStatus` field. > [!TIP] > > Don’t have a lead ID? Use [`GET /api/check-availability?address=%2B12025551234`](/api-reference/endpoint/check-availability) to check any phone or email directly. No saved lead required. ## Authentication ```bash theme={null} Authorization: Bearer tuco_xxxxxxxxxxxxx ``` ## Query parameters **id** `string` *required* The lead’s ID (MongoDB ObjectId). Example: `667f1f77bcf86cd799439012` ## Example ```bash theme={null} curl "https://app.tuco.ai/api/leads/check-availability?id=667f1f77bcf86cd799439012" \ -H "Authorization: Bearer tuco_xxxxxxxxxxxxx" ``` ## Success response (200) ```json theme={null} { "success": true, "leadId": "667f1f77bcf86cd799439012", "available": true, "status": "available", "ghlContactId": "aMUQn0u0Z7cw0NQ7tJ5R", "ghlLocationId": "eL7DD22BdZ0rismu7qCA", "hsPortalId": null, "hsContactId": null } ``` **success** `boolean` Always `true` on a 200 response. **leadId** `string` The lead ID that was checked. **available** `boolean` Whether the lead is reachable via iMessage. **status** `string` One of: * `"available"` — at least one stored address supports iMessage * `"unavailable"` — none of the stored addresses support iMessage * `"error"` — the check failed (temporary issue) **ghlContactId** `string | null` GoHighLevel contact ID, if linked. **ghlLocationId** `string | null` GoHighLevel location ID, if linked. **hsPortalId** `string | null` HubSpot portal ID, if linked. **hsContactId** `string | null` HubSpot contact ID, if linked. The same status is written back to the lead, so you can also read it via the Leads API. ## Error responses | Status | When | Body | | - | - | - | | `400` | Missing `id` parameter | `{ "error": "Lead ID is required" }` | | `401` | Invalid or missing API key | `{ "error": "Unauthorized" }` | | `404` | Lead not found | `{ "error": "Lead not found" }` | | `429` | API rate limit exceeded (200 req/min) | `{ "error": "Rate limit exceeded" }` | | `429` | All lines hit daily cap (70/day/line) | `{ "error": "Daily availability check quota exhausted" }` | | `500` | Internal server error | `{ "error": "Internal server error" }` | # Force a Line Health Check Source: https://docs.tuco.ai/api-reference/endpoint/line-health-check GET /api/lines/check-availability Trigger a fresh server ping and iMessage availability probe on one Tuco line, and write the result to its healthCheck. Uses the workspace API key. > [!NOTE] > > [`/api/lines/by-user`](/api-reference/endpoint/get-lines) reports the **last** > health check. This triggers a **new** one — use it when a line looks unhealthy > and you want to know whether it still is. ## Endpoint * **Method**: `GET` * **Path**: `/api/lines/check-availability?id={lineId}` * **Auth**: `Authorization: Bearer tuco_xxxxxxxxxxxxx` (workspace key) ```bash theme={null} curl "https://app.tuco.ai/api/lines/check-availability?id=6a3d7d7ef8c81f91304ed6f1" \ -H "Authorization: Bearer tuco_xxxxxxxxxxxxx" ``` The probe pings the line's server and checks iMessage availability, then writes the result to the line's `healthCheck`, so a following `/api/lines/by-user` shows the fresh state. Only lines in the workspace the key belongs to can be checked. An [agency key](/api-reference/agency-api-keys) is refused — pick the client's own key, since "which line" is a per-workspace question. ## Error responses | Status | When | | - | - | | `400` | `id` missing, or the line has no server configuration to probe | | `401` | Missing or invalid key | | `403` | An agency key (`tucoagency_…`) was used | | `404` | No such line in this workspace | # Line Plan Limits Source: https://docs.tuco.ai/api-reference/endpoint/line-limits GET /api/lines/limits Read how many phone and email lines your plan allows, how many you already have, and whether another one can be created. Pre-flight for POST /api/line-requests. > [!NOTE] > > Call this **before** [`POST /api/line-requests`](/api-reference/endpoint/create-line-request) to > know whether a new line is included, needs payment, or is not allowed at all on the current plan. ## Authentication Pass your workspace API key as a Bearer token, or use a Clerk session token. ```bash theme={null} Authorization: Bearer tuco_xxxxxxxxxxxxx ``` *** ## Example ```bash theme={null} curl "https://app.tuco.ai/api/lines/limits" \ -H "Authorization: Bearer tuco_xxxxxxxxxxxxx" ``` ### Success (`200 OK`) ```json theme={null} { "plan": "starter", "planName": "Starter", "limits": { "maxPhoneLines": 1, "maxEmailLines": 0, "maxPhoneAddons": 0, "maxEmailAddons": -1, "effectiveMaxPhoneLines": 1, "effectiveMaxEmailLines": 0 }, "addons": { "currentPhoneAddonQuantity": 0, "currentEmailAddonQuantity": 0, "remainingPurchasablePhoneAddons": 0, "remainingPurchasableEmailAddons": -1 }, "current": { "phoneLines": 1, "emailLines": 1 }, "canCreatePhone": false, "canCreateEmail": true } ``` > [!WARNING] > > **`-1` means unlimited**, not zero. Check for `-1` before comparing a count against a limit. ## Response **plan** `string | null` Plan id, e.g. `starter`. `null` when there is no active subscription. **planName** `string` Human-readable plan name. **limits** `object` Plan ceilings. `effectiveMaxPhoneLines` / `effectiveMaxEmailLines` already include purchased add-ons — compare against those, not the raw max. **addons** `object` Add-ons bought so far and how many more can still be bought. **current** `object` `phoneLines` and `emailLines` the workspace has today. **canCreatePhone** `boolean` Whether a phone line can be created right now. **canCreateEmail** `boolean` Whether an email line can be created right now. **error** `string` Only present when there is no active subscription: `"No active subscription"`, with every limit `0` and both `canCreate*` flags `false`. *** ## Errors | Status | When | Body | | - | - | - | | `400` | Key has no active workspace | `{ "error": "No active workspace" }` | | `401` | Missing or invalid API key | `{ "error": "Unauthorized" }` | # List / Check Do-Not-Contact Source: https://docs.tuco.ai/api-reference/endpoint/list-dnc GET /api/dnc List your workspace's Do-Not-Contact entries, poll for new opt-outs with since=, or check one phone number or email. Tuco AI iMessage API, bearer-token auth. > [!NOTE] > > Use this to stop contacts on your other channels (WhatsApp, email, dialer) when they opt out on iMessage. Poll with `since=`, or subscribe to the [`dnc.added` webhook](/api-reference/message-webhooks#dnc-added) to hear about each opt-out as it happens. ## Authentication ```bash theme={null} Authorization: Bearer tuco_xxxxxxxxxxxxx ``` Rate limit: 120 requests per minute per workspace (`429` with `Retry-After`). Without `since`, entries are returned newest first. *** ## Examples ```bash Poll for new opt-outs theme={null} curl "https://app.tuco.ai/api/dnc?since=2026-10-19T11:32:45Z&limit=200" \ -H "Authorization: Bearer tuco_xxxxxxxxxxxxx" ``` ```bash Check one number theme={null} curl "https://app.tuco.ai/api/dnc?phone=%2B15550100777" \ -H "Authorization: Bearer tuco_xxxxxxxxxxxxx" ``` ```bash List all (paged) theme={null} curl "https://app.tuco.ai/api/dnc?page=1&limit=200" \ -H "Authorization: Bearer tuco_xxxxxxxxxxxxx" ``` ### Polling loop 1. Store the `addedAt` of the last entry you processed (start with any past date). 2. Call `GET /api/dnc?since=&limit=200`. 3. Skip ids you have already processed; process the rest. 4. If `hasMore` is `true`, read `page=2`, `page=3`, … with the same `since`. 5. Save the last entry's `addedAt` and repeat (every few minutes is plenty). *** ## Success response (200) ```json Check one number theme={null} { "entries": [ { "id": "6ad5ffeb89a6125f30a7dd2c", "phone": "+15550100777", "email": null, "reason": "opt-out", "addedBy": "system", "addedAt": "2026-10-19T11:32:59.433Z", "source": "keyword-STOP" } ], "total": 1, "page": 1, "limit": 50, "totalPages": 1, "hasMore": false, "listed": true } ``` ## Errors | Status | When | | - | - | | `400` | `since` is not a valid date | | `401` | Missing or invalid API key | | `429` | Rate limit exceeded | # List Goal Bots Source: https://docs.tuco.ai/api-reference/endpoint/list-goal-bots GET /api/goal-bots List all AI goal bots in your Tuco AI workspace — returns goal, persona, status (active or archived), approval mode, and enrollment counts for each bot. > [!NOTE] > > **Goal bots and task agents are the same object.** The two engines merged; `/api/goal-bots` > and `/api/tasks` are aliases over one collection and return identical bodies. Every response > carries both `goalBot` and `taskAgent` (or `goalBots` and `taskAgents`) so integrations written > against either name keep working. > > The older stage-based engine moved to [`/api/instructions`](/api-reference/endpoint/list-instruction-bots) > and is being retired. Returns every goal bot in the workspace, **newest first**, with the built-in **Auto Replies** bot pinned to the top. There are no query parameters — the workspace comes from your API key. ## Authentication Pass your workspace API key as a Bearer token, or use a Clerk session token. ```bash theme={null} Authorization: Bearer tuco_xxxxxxxxxxxxx ``` *** ## Example ```bash theme={null} curl "https://app.tuco.ai/api/goal-bots" \ -H "Authorization: Bearer tuco_xxxxxxxxxxxxx" ``` ### Success (`200 OK`) ```json theme={null} { "goalBots": [ { "_id": "6aa9813105bb2cbf5931ac1f", "name": "Auto Replies", "prompt": "You're Raj from Tuco. You text people who checked out Tuco...", "mode": "autopilot", "status": "active", "connector": "calendly", "includeTags": [], "excludeTags": [], "kbRetrieval": "always", "canAsk": true, "maxTurns": 8, "typingIndicator": true, "writeTagToCrm": false, "isDefault": true, "createdAt": "2026-09-03T18:11:29.004Z", "updatedAt": "2026-10-02T09:40:12.551Z" } ], "taskAgents": [ /* identical array */ ] } ``` > [!NOTE] > > The first call from a brand-new workspace **creates** the default **Auto Replies** bot, so this > endpoint never returns an empty list. That bot is marked `isDefault: true` and cannot be deleted — > set its `mode` to `manual` to stop it. ## Response **goalBots** `object[]` Every bot in the workspace. Default bot first, then newest first. **Goal bot fields** **\_id** `string` Bot id. Use it on every `{id}` route. **name** `string` Display name. **prompt** `string` The instructions the model runs on. **mode** `string` `autopilot`, `copilot`, `manual`, or the legacy alias `draft`. **status** `string` `active` or `paused`. **connector** `string` `calendly` or `ghl_calendar`. **includeTags** `string[]` Tags that wake the bot. **excludeTags** `string[]` Tags that keep it out. **kbRetrieval** `string` `always` or `auto`. **canAsk** `boolean` Whether the bot may ask follow-up questions. **maxTurns** `number` Reply cap per conversation. **typingIndicator** `boolean` Whether it sends a typing signal before replying. **writeTagToCrm** `boolean` Whether `onDoneTag` is pushed to the connected CRM. **onDoneTag** `string` Tag applied when the bot finishes. **allowedToolIds** `string[]` Ids from [`GET /api/campaign-tools`](/api-reference/endpoint/list-tools) the bot may call. **collectFields** `string[]` Fields the bot tries to collect. **isDefault** `boolean` `true` for the built-in **Auto Replies** bot, which cannot be deleted. **createdAt** `string` ISO 8601 timestamp. **updatedAt** `string` ISO 8601 timestamp. **taskAgents** `object[]` The same array under the pre-rename key. Read either one. *** ## Errors | Status | When | Body | | - | - | - | | `400` | Key has no active workspace | `{ "error": "No active workspace" }` | | `401` | Missing or invalid API key | `{ "error": "Unauthorized" }` | # List Instruction Bots (retired) Source: https://docs.tuco.ai/api-reference/endpoint/list-instruction-bots GET /api/instructions List the retired stage-based instruction bots that used to answer on /api/goal-bots. They stay up for existing integrations; build on goal bots. > [!WARNING] > > **Instruction bots are being retired.** They are the older stage-based engine: a lead is > *enrolled* into one and walks a sequence of stages. The engine that replaced them — > [goal bots](/api-reference/endpoint/list-goal-bots) — has no stages and no enrolment: you tag a > lead and the bot handles their replies. > > Build new work on goal bots. These endpoints stay up for integrations already using them. Returns every **non-archived** instruction bot in the workspace, newest first. No query parameters. ## Authentication Pass your workspace API key as a Bearer token, or use a Clerk session token. ```bash theme={null} Authorization: Bearer tuco_xxxxxxxxxxxxx ``` *** ## Example ```bash theme={null} curl "https://app.tuco.ai/api/instructions" \ -H "Authorization: Bearer tuco_xxxxxxxxxxxxx" ``` ### Success (`200 OK`) ```json theme={null} { "goalBots": [ { "_id": "6a970c3429603484fb08b211", "name": "Escalate Wedding Lead", "description": "Recognise when a wedding lead should be handled by a human...", "goal": "Hand the conversation to a human when it exceeds the bot's authority", "status": "active", "stages": [ /* ordered stages */ ], "stats": { "totalEnrolled": 12, "inProgress": 3 }, "createdAt": "2026-09-01T12:04:52.188Z" } ] } ``` > [!WARNING] > > The response key is **`goalBots`**, not `instructions` — a historical name from before the engines > split. These are instruction bots, and their ids are **not** interchangeable with > [goal bot](/api-reference/endpoint/list-goal-bots) ids: the two live in different collections. ## Response **goalBots** `object[]` Non-archived instruction bots, newest first. **Instruction bot fields** **\_id** `string` Instruction id. Use it on the enrol routes. **name** `string` Display name. **description** `string` Optional description. **goal** `string` What the bot is trying to achieve. **status** `string` `active`, `draft` or `paused`. Only `active` bots accept enrolments. **stages** `object[]` The ordered stages the lead walks. **settings** `object` Tone, model and per-conversation reply cap. **entry** `object` How leads enter, including `tag_trigger`. **stats** `object` `totalEnrolled` and `inProgress` counts. **createdAt** `string` ISO 8601 timestamp. *** ## Errors | Status | When | Body | | - | - | - | | `401` | Missing or invalid API key | `{ "error": "Unauthorized" }` | # List Lead Lists Source: https://docs.tuco.ai/api-reference/endpoint/list-lists GET /api/lists List every lead list in your Tuco workspace with its lead count — the source of the listId used when creating leads or running a bulk availability check. > [!NOTE] > > A **list** owns leads. `listId` is what you pass to > [`POST /api/leads`](/api-reference/endpoint/create) to file new leads somewhere specific, and to > [`POST /api/leads/check-availability`](/api-reference/endpoint/bulk-check-availability) to check a > whole list at once. These endpoints are how you get a `listId` without opening the dashboard. Returns every list in the workspace, **newest first**. No query parameters. ## Authentication Pass your workspace API key as a Bearer token, or use a Clerk session token. ```bash theme={null} Authorization: Bearer tuco_xxxxxxxxxxxxx ``` *** ## Example ```bash theme={null} curl "https://app.tuco.ai/api/lists" \ -H "Authorization: Bearer tuco_xxxxxxxxxxxxx" ``` ### Success (`200 OK`) ```json theme={null} { "lists": [ { "_id": "6aab49a066aa3784fa345a0a", "name": "Close Import", "description": "Contacts imported from Close", "workspaceId": "org_3CzFir0Fps4hHL4nbU9WQ6FR4ur", "createdByUserId": "user_34tKD7C7oYWFSBH4JBvbSgO8de5", "leadCount": 4, "createdAt": "2026-09-17T02:00:00.189Z", "updatedAt": "2026-09-21T16:50:19.878Z" } ] } ``` > [!NOTE] > > The **Quick Sends** list is created on the first call if it does not exist, so this endpoint never > returns an empty array. Quick Sends is where leads go when you send to a phone number that has no > saved lead yet, and when you omit `listId` on [`POST /api/leads`](/api-reference/endpoint/create). ## Response **lists** `object[]` Every list in the workspace, newest first. **List fields** **\_id** `string` The list id. This is the `listId` other endpoints take. **name** `string` List name. Unique within the workspace. **description** `string` Optional description. **leadCount** `number` How many leads the list holds. **createdByUserId** `string` Clerk user id of whoever created it. **createdAt** `string` ISO 8601 timestamp. **updatedAt** `string` ISO 8601 timestamp. *** ## Errors | Status | When | Body | | - | - | - | | `401` | Missing or invalid API key | `{ "error": "Unauthorized" }` | | `429` | More than 120 requests/min for this workspace | `{ "error": "Rate limit exceeded" }` | # List Recordings & Uploads Endpoint Source: https://docs.tuco.ai/api-reference/endpoint/list-recordings GET /api/attachments/list List every call recording and uploaded file in your Tuco workspace, newest first, with signed playback links. Beta endpoint, bearer-token auth. > [!NOTE] > > This endpoint is in **beta**. The interface is stable enough to build on; we may add fields as it matures. ## Overview Returns two separate lists for your workspace: * **`recordings`** — audio from calls placed on your Tuco line, captured automatically. * **`items`** — files *you* uploaded, via [Upload attachment](/api-reference/upload-attachment) or the **Leads → Upload audio etc** tab. Use this when you want everything in the workspace. To pull the calls made to one specific lead, use [Get call recordings](/api-reference/endpoint/get-recordings) instead — that endpoint takes a phone number and returns full call timing. *** ## Making a request * **Method**: `GET` * **URL**: `https://app.tuco.ai/api/attachments/list` * **Headers**: `Authorization: Bearer tuco_...` ```bash theme={null} curl "https://app.tuco.ai/api/attachments/list?limit=20" \ -H "Authorization: Bearer tuco_your_key" ``` ### Query parameters **limit** `number` Max entries to return per list. Default `20`, min `1`, max `100`. **cursor** `string` Opaque cursor from a previous response's `nextCursor`, to page through **uploads**. **recordingsCursor** `string` Opaque cursor from a previous response's `recordingsNextCursor`, to page through **recordings**. Recordings and uploads paginate independently — see [Paging](#paging). *** ## Response ```json theme={null} { "recordings": [ { "url": "https://app.tuco.ai/api/attachments/crm-media/6aac0729....mp3?u=...&exp=...&sig=...", "name": "Call → +15145550123 · 3:40", "size": 878733, "uploadedAt": "2026-09-17T15:28:41.632Z", "pathname": "workspaces/org_.../recordings/6aac0729....mp3", "isAudio": true, "kind": "recording", "callId": "6aac072927e54a4003b72623", "toE164": "+15145550123", "fromE164": "+13025550999", "durationSec": 220 } ], "recordingsNextCursor": null, "recordingsHasMore": false, "items": [ { "url": "https://app.tuco.ai/api/attachments/crm-media/vn.m4a?u=...&exp=...&sig=...", "name": "vn.m4a", "size": 45056, "uploadedAt": "2026-09-18T10:02:11.000Z", "pathname": "workspaces/org_.../attachments/....m4a", "isAudio": true, "kind": "upload" } ], "nextCursor": null, "hasMore": false } ``` **recordings** `array` Call recordings, newest first. **recording fields** **url** `string` Signed playback/download URL. See [Links expire](#links-expire). **name** `string` Display label, e.g. `Call → +15145550123 · 3:40`. **size** `number` File size in bytes. **uploadedAt** `string` When the call was answered; falls back to when it was requested, then to when the audio was stored. **pathname** `string` Internal storage path. Informational only. **isAudio** `boolean` Always `true` for recordings. **kind** `string` Always `recording`. Use this to tell the two lists apart if you merge them. **callId** `string` The call's ID — pass it to your own systems, or match it against [Get call recordings](/api-reference/endpoint/get-recordings). **toE164** `string` Number that was called. `null` if the call record is unavailable. **fromE164** `string` Caller ID the lead saw. `null` if the call record is unavailable. **durationSec** `number` Talk time in seconds. `null` if the call record is unavailable. **recordingsNextCursor** `string` Cursor for the next page of recordings, or `null`. **recordingsHasMore** `boolean` Whether more recordings exist beyond this page. **items** `array` Files you uploaded, newest first. **upload fields** **url** `string` Signed download URL. **name** `string` Original filename. **size** `number` File size in bytes. **uploadedAt** `string` When it was uploaded. **pathname** `string` Internal storage path. Informational only. **isAudio** `boolean` Whether the file is a supported audio type. **kind** `string` Always `upload`. **nextCursor** `string` Cursor for the next page of uploads, or `null`. **hasMore** `boolean` Whether more uploads exist beyond this page. *** ## Paging Recordings and uploads are **paged independently**, each with its own cursor. Pass `recordingsCursor` to advance recordings and `cursor` to advance uploads; you can send both, either, or neither. ```bash theme={null} # next page of recordings only curl "https://app.tuco.ai/api/attachments/list?limit=20&recordingsCursor=CURSOR_FROM_LAST_RESPONSE" \ -H "Authorization: Bearer tuco_your_key" ``` > [!NOTE] > > `limit` applies to **each** list, so `limit=20` can return up to 20 recordings *and* > up to 20 uploads in one response. ## Links expire > [!WARNING] > > Every `url` is a **signed link that expires**. Do not store it — keep the `callId` > (for recordings) or `pathname`, and call this endpoint again when you need fresh > links. The audio itself is kept indefinitely; only the link is time-limited. Links from this endpoint are valid for **1 year**. Note that the same recording requested via [Get call recordings](/api-reference/endpoint/get-recordings) returns a link valid for **30 days** — treat both as short-lived and re-fetch rather than caching either. ## Format Call recordings are **MP3, mono** — both sides of the conversation are mixed into a single channel. Good for playback and transcription; not suited to separating the speakers. ## Scope You only ever see your own workspace's recordings and uploads. The API key you authenticate with determines the workspace, and there is no parameter to query another one. *** ## Errors | HTTP | Meaning | | - | - | | 401 | Missing or invalid API key | | 500 | Unexpected server error — the response body is `{ "error": "Could not load your uploads. Please try again." }` | # List Task Agents Source: https://docs.tuco.ai/api-reference/endpoint/list-task-agents GET /api/tasks List the task agents in a Tuco workspace, newest first, with the built-in Auto Replies bot pinned to the top. No query parameters; API key auth. > [!NOTE] > > **This is an alias.** `GET /api/tasks` and > [`GET /api/goal-bots`](/api-reference/endpoint/list-goal-bots) are the same route over the same > collection and return identical bodies. `/api/tasks` is not deprecated — it is the name > integrations built before the rename already use. Returns every bot in the workspace, **newest first**, with the built-in **Auto Replies** bot pinned to the top. No query parameters. ## Authentication Pass your workspace API key as a Bearer token, or use a Clerk session token. ```bash theme={null} Authorization: Bearer tuco_xxxxxxxxxxxxx ``` *** ## Example ```bash theme={null} curl "https://app.tuco.ai/api/tasks" \ -H "Authorization: Bearer tuco_xxxxxxxxxxxxx" ``` ### Success (`200 OK`) ```json theme={null} { "goalBots": [ { "_id": "6aa9813105bb2cbf5931ac1f", "name": "Auto Replies", "mode": "autopilot", "status": "active", "isDefault": true, "createdAt": "2026-09-03T18:11:29.004Z" } ], "taskAgents": [ /* identical array */ ] } ``` > [!NOTE] > > Both keys are always present. `goalBots` is what the dashboard and these docs call them; > `taskAgents` is the pre-rename key. Read either. See [List Goal Bots](/api-reference/endpoint/list-goal-bots) for the full field reference. *** ## Errors | Status | When | Body | | - | - | - | | `400` | Key has no active workspace | `{ "error": "No active workspace" }` | | `401` | Missing or invalid API key | `{ "error": "Unauthorized" }` | # List API Tools Source: https://docs.tuco.ai/api-reference/endpoint/list-tools GET /api/campaign-tools List all custom API tools registered in your Tuco AI workspace — tools that goal bots can call to fetch lead data or trigger external actions. > [!NOTE] > > An API tool lets a goal bot call **your** endpoint mid-conversation — check stock, look up an > order, fetch a balance — and use the answer in its reply. Attach a tool to a bot by putting its > `_id` in that bot's `allowedToolIds`. Returns every tool in the workspace, **oldest first**. No query parameters — the workspace comes from your API key. ## Authentication Pass your workspace API key as a Bearer token, or use a Clerk session token. ```bash theme={null} Authorization: Bearer tuco_xxxxxxxxxxxxx ``` *** ## Example ```bash theme={null} curl "https://app.tuco.ai/api/campaign-tools" \ -H "Authorization: Bearer tuco_xxxxxxxxxxxxx" ``` ### Success (`200 OK`) ```json theme={null} { "tools": [ { "_id": "6ac3ed9271adb32c88d566e0", "workspaceId": "org_3CzFir0Fps4hHL4nbU9WQ6FR4ur", "name": "check_stock", "description": "Returns current stock for a SKU", "method": "GET", "url": "https://api.example.com/stock", "responseMapping": "data.quantity", "variableKey": "api_check_stock", "createdAt": "2026-10-05T18:33:54.781Z", "updatedAt": "2026-10-05T18:33:54.781Z" } ] } ``` ## Response **tools** `object[]` Every tool in the workspace, oldest first. Empty array when there are none. **Tool fields** **\_id** `string` Tool id. Pass it as `id` to update or delete. **name** `string` Tool name. **description** `string` What the tool does — this is what the model reads when deciding to call it. **method** `string` `GET`, `POST`, `PUT`, `PATCH` or `DELETE`. **url** `string` The endpoint Tuco calls. **headers** `object` Headers sent with the call. **body** `string` Request body template, if any. **responseMapping** `string` Dot path into the response that becomes the tool's value. **variableKey** `string` Derived from `name` — the variable the bot reads the result from, e.g. `api_check_stock`. **createdAt** `string` ISO 8601 timestamp. **updatedAt** `string` ISO 8601 timestamp. *** ## Errors | Status | When | Body | | - | - | - | | `401` | Missing or invalid API key | `{ "error": "Unauthorized" }` | # List Webhook Deliveries Source: https://docs.tuco.ai/api-reference/endpoint/list-webhook-deliveries GET /api/webhooks/{id}/deliveries List every delivery Tuco made to one webhook in the last 30 days: event, your endpoint's status code, latency and attempts. Cursor-paginated. Newest first. Deliveries are kept for **30 days**. Includes live events, tests and replays. ## Authentication ```bash theme={null} Authorization: Bearer tuco_xxxxxxxxxxxxx ``` ## Path parameters **id** `string` *required* Webhook ID. ## Query parameters **limit** `number` (default: 25) Page size, 1–100. **status** `string` `success` or `failed`. **event** `string` Only this event, e.g. `message.sent`. **cursor** `string` `nextCursor` from the previous page. ## Response **deliveries** `array` **delivery** **id** `string` Delivery id. Use it to get or replay the delivery. **event** `string` Event type. **eventId** `string | null` `X-Tuco-Event-Id` that was sent. **deliveryId** `string | null` `X-Tuco-Delivery-Id` that was sent. **messageId** `string | null` Tuco message id, when the event has one. **status** `string` `success` (your endpoint returned 2xx) or `failed`. **responseStatus** `number | null` Your endpoint's final HTTP status. `null` on a timeout or network error. **error** `string | null` Why it failed. **latencyMs** `number` Total time including the retry. **attemptCount** `number` 1, or 2 when Tuco retried. **isTest** `boolean` Sent by the test endpoint. **isReplayOf** `string | null` For a replay: the id of the original delivery. **url** `string` Endpoint URL it was sent to. **createdAt** `string` ISO 8601 UTC. **nextCursor** `string | null` Pass as `cursor` for the next page. `null` on the last page. | Status | When | | - | - | | `200` | OK | | `400` | Invalid `limit`, `status` or `cursor` | | `401` | Missing or invalid API key | | `404` | Webhook not found in your workspace | ## Example ```bash theme={null} curl "https://app.tuco.ai/api/webhooks/680a1b2c3d4e5f6789012345/deliveries?status=failed&limit=2" \ -H "Authorization: Bearer tuco_xxxxxxxxxxxxx" ``` ```json theme={null} { "deliveries": [ { "id": "6ad14a1e2f9c4b0012ab34cd", "event": "message.sent", "eventId": "evt_3f1c9a7e52b04d8a9c61e0f2", "deliveryId": "dlv_8b2d4e6f10a3c5e7f9b1d3a5", "messageId": "6ad119046e345bcbe00cd99b", "status": "failed", "responseStatus": 503, "error": "HTTP 503: Service Unavailable", "latencyMs": 5231, "attemptCount": 2, "isTest": false, "isReplayOf": null, "url": "https://hooks.example.com/tuco", "createdAt": "2026-10-16T09:12:44.512Z" } ], "nextCursor": "6ad14a1e2f9c4b0012ab34cd" } ``` # List Webhooks Source: https://docs.tuco.ai/api-reference/endpoint/list-webhooks GET /api/webhooks List all webhooks registered in your workspace. REST endpoint in the Tuco AI iMessage API — bearer-token auth, JSON request/response, full schema and code. Returns all webhooks for your workspace, sorted by creation date (newest first). Secrets are **never** returned. ## Authentication Pass your workspace API key as a Bearer token. ```bash theme={null} Authorization: Bearer tuco_xxxxxxxxxxxxx ``` *** ## Response **webhooks** `array` Array of webhook objects. Each includes: **Webhook fields** **id** `string` Webhook ID **url** `string` Endpoint URL **events** `string[]` Subscribed event types **name** `string` User-friendly name **description** `string | null` Optional description **isActive** `boolean` Whether the webhook is currently active **hasAuthHeader** `boolean` Whether a custom Authorization header is configured. The value itself is never returned. **lastTriggeredAt** `string | null` Last time any event was sent (ISO UTC) **lastSuccessAt** `string | null` Last successful delivery (ISO UTC) **lastFailureAt** `string | null` Last failed delivery (ISO UTC) **failureCount** `number` Consecutive failure count **createdAt** `string` Creation timestamp (ISO UTC) **updatedAt** `string` Last update timestamp (ISO UTC) *** ## Example ```bash theme={null} curl "https://app.tuco.ai/api/webhooks" \ -H "Authorization: Bearer tuco_xxxxxxxxxxxxx" ``` ```json 200 Response theme={null} { "webhooks": [ { "id": "680a1b2c3d4e5f6789012345", "url": "https://example.com/webhooks/tuco", "events": ["message.sent", "message.failed", "message.reply"], "name": "Production webhook", "description": "Sends events to our CRM", "isActive": true, "hasAuthHeader": false, "lastTriggeredAt": "2026-04-12T10:30:00.000Z", "lastSuccessAt": "2026-04-12T10:30:00.000Z", "lastFailureAt": null, "failureCount": 0, "createdAt": "2026-03-01T00:00:00.000Z", "updatedAt": "2026-04-12T10:30:00.000Z" } ] } ``` # Manage Line Request Source: https://docs.tuco.ai/api-reference/endpoint/manage-line-request POST /api/line-requests/{id} Cancel a pending Tuco line request or recover its Stripe payment link. Doesn't create new requests. Bearer-token REST endpoint in the Tuco API. > [!NOTE] > > This endpoint supports small request-management actions. It does not create a new line request. ## When To Use This Endpoint Use this endpoint when the request already exists and the user asks one of these questions: * "I lost the payment link. Can I get it again?" * "I changed my mind. Can I cancel this unpaid request?" This endpoint is only for requests that are still pending payment. ## Authentication Pass your workspace API key as a Bearer token, or use a Clerk session token. ```bash theme={null} Authorization: Bearer tuco_xxxxxxxxxxxxx ``` *** ## Path parameter **id** `string` *required* The line request id returned by `POST /api/line-requests` — it is the `line._id` value in that response. A line request is not a separate record: it is the line itself, created with `requestSource: "api"`. The request id and the line id are therefore the same value. Unlike [`GET /api/line-requests/{id}`](/api-reference/endpoint/get-line-request), which reads any line in your workspace, these two actions run only against API-created requests — a line created in the dashboard returns `404 Line request not found`. *** ## Request body **action** `string` *required* Which action to run. One of `"payment_link"` or `"cancel"` — any other value returns `400 Unsupported action`, and so does an empty body. *** ## Supported actions | Action | What it does | | - | - | | `payment_link` | Returns the hosted invoice link again for an `awaiting_payment` request | | `cancel` | Cancels an `awaiting_payment` request so it no longer blocks a new purchase | Both actions only apply to pending-payment requests. If the request is already in `provisioning`, `active`, `failed`, or `canceled`, these actions no longer apply. *** ## Recover payment link ```bash theme={null} curl -X POST "https://app.tuco.ai/api/line-requests/6a092ebde4a7fbddc8a832da" \ -H "Authorization: Bearer tuco_xxxxxxxxxxxxx" \ -H "Content-Type: application/json" \ -d '{ "action": "payment_link" }' ``` ### Success (`200 OK`) ```json theme={null} { "success": true, "status": "awaiting_payment", "paymentUrl": "https://invoice.stripe.com/...", "invoiceId": "in_123", "reused": true } ``` If the workspace entitlement has already updated, the same action can promote the line and return a normal provisioning response instead. That means `payment_link` can act like a safe recovery action: * if payment is still needed, it gives you the invoice again * if payment has already been reconciled, it can return the updated provisioning state instead *** ## Cancel pending request ```bash theme={null} curl -X POST "https://app.tuco.ai/api/line-requests/6a092ebde4a7fbddc8a832da" \ -H "Authorization: Bearer tuco_xxxxxxxxxxxxx" \ -H "Content-Type: application/json" \ -d '{ "action": "cancel" }' ``` ### Success (`200 OK`) ```json theme={null} { "success": true, "status": "canceled", "line": { "_id": "6a092ebde4a7fbddc8a832da", "provisioningStatus": "canceled", "paymentStatus": "failed" } } ``` After canceling, the workspace can create a different line request without waiting on the old unpaid one. *** ## Error responses | Status | When | Body | | - | - | - | | `400` | Invalid line request id or unsupported action | `{ "error": "Invalid line request id" }` or `{ "error": "Unsupported action" }` | | `401` | Missing or invalid API key / session | `{ "error": "Unauthorized" }` | | `403` | `payment_link` used without an active subscription | `{ "success": false, "status": "subscription_required", "message": "...", "redirect": "/billing" }` | | `404` | Request not found in your workspace | `{ "error": "Line request not found" }` | | `409` | Action does not apply to the current request state | `{ "success": false, "status": "...", "message": "..." }` | # Message Status Source: https://docs.tuco.ai/api-reference/endpoint/message-journey GET /api/messages/{messageId}/journey A step-by-step timeline of what happened to one message — every retry, fallback and failure, in plain language. > [!NOTE] > > Answers the question your customer actually asks: *"why didn't it arrive?"* Make > this your tier-1 support screen. ## Endpoint * **Method**: `GET` * **Path**: `/api/messages/{messageId}/journey` * **Auth**: `Authorization: Bearer tuco_xxxxxxxxxxxxx` (workspace key) ```bash theme={null} curl https://app.tuco.ai/api/messages/6ac55dceca1db6f898e065cc/journey \ -H "Authorization: Bearer tuco_xxxxxxxxxxxxx" ``` ## Response Not a status string — a **timeline**. Each step records when it happened, how serious it is, which system reported it, and copy you can show a human as-is. ```json theme={null} { "steps": [ { "at": 1791315902559, "tier": "info", "system": "app", "key": "queued", "label": "Send requested", "copy": "Message queued to send." }, { "at": 1791315903880, "tier": "ok", "system": "imessage", "key": "sent", "label": "Sent as iMessage", "copy": "Delivered to your contact's iMessage." } ], "meta": { "source": "loki", "env": "prod", "count": 2 } } ``` | Field | Meaning | | - | - | | `at` | Epoch milliseconds | | `tier` | `ok`, `info`, `warn` or `crit` — colour it, sort by it. Note **`ok`, not `success`**, and **`crit`, not `error`** | | `system` | Which part reported it: `app`, `device`, `imessage`, `ghl`, `hubspot` | | `key` | Stable machine key — branch on this, not on `copy` | | `label` / `copy` | Short title and a sentence written for an end user | `meta` describes where the timeline was assembled from (`source`, `env`) and how many steps it holds. Render `copy` directly. Branch on `key`. The timeline includes retries, the fallback ladder (iMessage → SMS → email) and the reason for any failure, so a message that fell back shows both legs rather than just the final state. ## Error responses | Status | When | | - | - | | `401` | Missing or invalid key | | `403` | The message belongs to another workspace, or an agency key was used | | `404` | No such message | # Place a Call Endpoint Source: https://docs.tuco.ai/api-reference/endpoint/place-call POST /api/voice/calls Place an outbound click-to-call from your own system: Tuco dials your agent, dials the lead from your Tuco number, and bridges the two. > [!WARNING] > > **The Try it panel runs against production** (`https://app.tuco.ai`) with the key you paste > into it. There is no sandbox — a request from this page places a real phone call and bills real minutes. > [!NOTE] > > This endpoint is in **beta**. The interface is stable enough to build on; we may add fields as it matures. ## Overview Place an outbound call programmatically with a single request. Tuco rings your agent first, then dials the lead **from your Tuco number**, and bridges the two legs — so the lead sees the same number they've been texting, and your rep's personal number is never exposed. > [!NOTE] > > US and Canada (`+1`) numbers only. *** ## What you'll need Three things before you make a request: **1. Your API key** A workspace API key (starts with `tuco_`). Get it in the Tuco dashboard under **Settings → Integrations → API Keys → Create API Key**. Send it as a bearer token: `Authorization: Bearer tuco_...`. This is the same key used for the Messages API. **2. A voice-verified calling line** The call goes out **from a line in your workspace whose caller ID is voice-verified** — that's the number the recipient sees. Pass it as `from`, using **either**: * the line's **`+1` number** — simplest, no lookup needed, or * the **line ID** — go to the **Lines** page in the dashboard; each line row has a **Copy Line ID** button (the copy icon next to the line) — click it to copy the ID. You can also get it from the [List Lines](/api-reference/lines) API (each line's `_id`). If the line isn't voice-verified yet, verify it in the dashboard (or ask your Tuco contact to enable voice on it). **3. Two phone numbers** The **lead** you want to reach (`to`) and **your rep's phone** (`agent`), both in E.164 format (US/CA, e.g. `+13025550123`). *** ## How it works ``` POST /api/voice/calls │ ├─ 1. Tuco dials your AGENT → your rep's phone rings first ├─ 2. agent answers → Tuco dials the LEAD from your Tuco number ├─ 3. lead answers → Tuco bridges the two legs └─ call is recorded, then billed on hangup ``` The lead is **only dialed after your agent answers**, so a lead is never left listening to dead air. *** ## Making a request * **Method**: `POST` * **URL**: `https://app.tuco.ai/api/voice/calls` * **Headers**: `Authorization: Bearer tuco_...` and `Content-Type: application/json` * **Body**: JSON with `from`, `to`, and `agent` ### Request body ```json theme={null} { "from": "69f918a0f62015705ca41fbb", "to": "+13025550123", "agent": "+13025550456" } ``` **from** `string` *required* Your calling line — pass either the **line ID** or the line's **`+1` number**. Must be a line in your workspace with a voice-verified caller ID. This is the number the lead sees. **to** `string` *required* The number to call, E.164 US/CA (e.g. `+13025550123`). Non-toll-free. This is just a phone number — **the contact does not need to exist in Tuco first**; you can call any US/CA number directly. **agent** `string` *required* Your rep's phone number, E.164 US/CA. This leg is dialed **first** — your rep answers, then the number is dialed and bridged in. **leadId** `string` Optional, advanced. Only if you already have a lead record in Tuco and want the call logged against it (shows in that lead's Unibox thread). Not required to place a call. ### Example ```bash theme={null} curl -X POST https://app.tuco.ai/api/voice/calls \ -H "Authorization: Bearer tuco_your_key" \ -H "Content-Type: application/json" \ -d '{ "from": "", "to": "+13025550123", "agent": "+13025550456" }' ``` *** ## Response **`202 Accepted`** — the call was accepted and is being placed. Ringing takes a few seconds, so the response returns a call ID immediately and the call then progresses asynchronously. ```json theme={null} { "callId": "6a4ed2d5dec1b2d01a6f7656", "status": "requested" } ``` **callId** `string` The call record ID (MongoDB ObjectId). **status** `string` Always `"requested"` on a successful create. *** ## Call lifecycle The call advances through these states on the call record: ``` requested → ringing → answered → billed ↘ failed ``` | State | Meaning | | - | - | | `requested` | Accepted; the agent leg is dialing | | `ringing` | A leg is ringing | | `answered` | Both legs connected and bridged | | `billed` | Call ended; `durationSec`, `billedSec`, and the recording URL are settled | | `failed` | The agent didn't answer, or the call couldn't be placed | Every call is recorded; the recording URL is attached to the call record once the call ends. > [!TIP] > > **Want the lead told the call is recorded?** Turn on the line's > [call recording notice](/api-reference/endpoint/update-line#call-recording-notice) > (`"callRecordingDisclosure": true`). When the lead answers, both they and your agent hear a short > "this call may be recorded" message, and it's on the recording. > [!NOTE] > > The `agent` leg rings first — your rep must answer within \~30 seconds or the call > times out. If the agent's phone goes to voicemail, the call ends without dialing > or bridging the lead. *** ## Getting the recording Recordings are captured automatically. After a call ends, fetch the recording (and the call's timing details) with the [Get Call Recordings](/api-reference/endpoint/get-recordings) endpoint, using the lead's number. To get the **most recent** call's recording for a lead, pass `latest=true`: ```bash theme={null} curl "https://app.tuco.ai/api/voice/recordings?number=%2B13025550123&latest=true" \ -H "Authorization: Bearer tuco_your_key" ``` The `recordingUrl` in the response is the download link. Drop `latest=true` to get all calls to that number (newest first). > [!NOTE] > > Recordings resolve a **few seconds after the call ends**. If you request right on > hangup and `recordingUrl` comes back `null`, wait \~5-10 seconds and retry. See the > [Get Call Recordings](/api-reference/endpoint/get-recordings) endpoint for all > parameters. *** ## Errors All errors return `{ "error": "...", "code": "..." }`. | HTTP | `code` | Meaning | | - | - | - | | 401 | `UNAUTHORIZED` | Missing or invalid API key | | 400 | `MISSING_FROM` | `from` (calling line) not provided | | 400 | `MISSING_TO` | `to` (lead number) not provided | | 400 | `MISSING_AGENT` | `agent` (rep number) not provided | | 400 | `INVALID_TO` | `to` is not a US/CA number, or is toll-free | | 400 | `INVALID_AGENT` | `agent` is not a US/CA number, or is toll-free | | 403 | `VOICE_NOT_ENABLED` | Voice calling is not enabled for this workspace | | 404 | `LINE_NOT_FOUND` | `from` line does not exist in your workspace | | 409 | `LINE_NOT_VERIFIED` | The line exists but its caller ID is not voice-verified | | 429 | `CONCURRENT_CAP` | Too many live calls on this line | | 429 | `LINE_MONTHLY_CAP` | The line hit its monthly minutes cap | | 402 | `MINUTES_EXHAUSTED` | The workspace is out of voice minutes | | 502 | `ORIGINATE_FAILED` | The carrier rejected the outbound dial | | 500 | `INTERNAL_ERROR` | Unexpected server error | # Replay Webhook Delivery Source: https://docs.tuco.ai/api-reference/endpoint/replay-webhook-delivery POST /api/webhooks/{id}/deliveries/{deliveryId}/replay Re-send a past webhook delivery to your endpoint: the exact same body, signed with your current secret, to your current URL. Re-sends the stored request body **byte for byte** to the webhook's **current** URL, signed with the webhook's **current** secret. Use it after fixing an endpoint that was down. The replay carries the original `X-Tuco-Event-Id` (so you can tell it is the same event), a new `X-Tuco-Delivery-Id`, and `X-Tuco-Replay: true`. It is recorded as a new delivery with `isReplayOf` pointing at the original. Replaying a replay points at the original too. ## Authentication ```bash theme={null} Authorization: Bearer tuco_xxxxxxxxxxxxx ``` ## Path parameters **id** `string` *required* Webhook ID. **deliveryId** `string` *required* Delivery `id` to re-send. ## Response **success** `boolean` Your endpoint returned 2xx. **deliveryId** `string` Id of the new delivery record. **isReplayOf** `string` Id of the original delivery. **responseStatus** `number | null` Your endpoint's HTTP status. **error** `string | null` Why it failed. **latencyMs** `number` Total time including any retry. **attemptCount** `number` 1 or 2. | Status | When | | - | - | | `200` | Replayed and your endpoint returned 2xx | | `502` | Replayed, but your endpoint did not return 2xx | | `401` | Missing or invalid API key | | `402` | Workspace is read-only (billing) | | `404` | Webhook or delivery not found in your workspace | | `409` | Webhook is inactive. Activate it first. | ## Example ```bash theme={null} curl -X POST "https://app.tuco.ai/api/webhooks/680a1b2c3d4e5f6789012345/deliveries/6ad14a1e2f9c4b0012ab34cd/replay" \ -H "Authorization: Bearer tuco_xxxxxxxxxxxxx" ``` ```json theme={null} { "success": true, "deliveryId": "6ad14b9a2f9c4b0012ab34d1", "isReplayOf": "6ad14a1e2f9c4b0012ab34cd", "responseStatus": 200, "error": null, "latencyMs": 184, "attemptCount": 1 } ``` # Reply Hours Source: https://docs.tuco.ai/api-reference/endpoint/reply-hours GET|PUT|DELETE /api/goal-bots/{id}/reply-hours Read, set and clear the days and times a goal bot is allowed to answer a lead. Outside them the bot sends nothing and a person answers instead. > [!NOTE] > > **Goal bots and task agents are the same object.** `/api/goal-bots/{id}/reply-hours` and > `/api/tasks/{id}/reply-hours` are aliases over one collection and behave identically. Each bot has its **own** hours. There is no workspace-wide schedule, so exactly one schedule decides any one reply. **A bot with no schedule answers at all times.** That is every bot until somebody sets one, so adding reply hours is the only thing that can ever make a bot quieter. The same field is editable through [`PATCH /api/goal-bots/{id}`](/api-reference/endpoint/update-goal-bot) as `replyHours`. Prefer this route for anything automated: it sends only the schedule, so a stale `prompt` in your payload cannot overwrite one somebody edited in the dashboard while your script was running. *** ## What happens outside the hours The bot **sends nothing and drafts nothing**. The owner still gets told. They receive the **ordinary new-reply email and Telegram** — the same ones a workspace with no bot at all gets for an inbound. No empty draft card, no handoff alert, nothing bot-shaped. Only the bot's work stops; the alerting is unchanged. > [!WARNING] > > **Nothing is queued.** The message is not answered later when the window reopens. There is no > catch-up job and no retry. From that point the conversation is manual — a person answers it, or > nobody does. *** ## Authentication Pass your workspace API key as a Bearer token, or use a Clerk session token. ```bash theme={null} Authorization: Bearer tuco_xxxxxxxxxxxxx ``` *** ## Path parameter **id** `string` *required* The bot id. A malformed id returns `400 Invalid id`. *** ## The schedule object ```json theme={null} { "days": { "mon": { "start": "09:00", "end": "17:00" }, "sat": { "start": "10:00", "end": "14:00" } }, "override": null } ``` **days** `object` A day that is **present** is a day the bot answers. A day that is **absent** is a day it does not. Keys are `mon` `tue` `wed` `thu` `fri` `sat` `sun`. An empty object `{}` means no schedule at all, so the bot answers always. **days.\{day}.start** `string` *required* `"HH:MM"`, 24-hour. **days.\{day}.end** `string` *required* `"HH:MM"`, 24-hour. **Exclusive** — `09:00`–`17:00` answers at 16:59 and does not answer at 17:00. An end **earlier** than the start is a **night shift**, not an error. See below. **override** `string | null` `"on"` answers at all times. `"off"` never answers. `null` follows `days`. An override beats the schedule and does **not** erase it — clear the override and your saved days apply again. **It has no expiry**: it holds until somebody changes it, so one set on a Friday is still set on Monday. ### Night shifts Set an end time **earlier** than the start time and the window runs past midnight. The hours belong to the day the shift **starts**. `20:00`–`08:00` on `mon` covers Monday evening **and Tuesday until 08:00** — so a lead writing at 02:00 on Tuesday is answered, because Monday's shift has not finished, and one writing at 09:00 on Tuesday is not. ```json theme={null} { "days": { "mon": { "start": "20:00", "end": "08:00" } } } ``` For a bot that answers every night, set the shift on each day it starts: ```json theme={null} { "days": { "mon": { "start": "20:00", "end": "08:00" }, "tue": { "start": "20:00", "end": "08:00" }, "wed": { "start": "20:00", "end": "08:00" }, "thu": { "start": "20:00", "end": "08:00" }, "fri": { "start": "20:00", "end": "08:00" } } } ``` That answers Monday night through Saturday 08:00, and stays quiet in the daytime gap between shifts. ### Rules the API enforces * `start` and `end` must **differ**. The same value for both is refused, because it cannot be told apart from "no time at all" or "the whole day". * Times are read in the **workspace timezone**, never the server's and never the lead's. `GET` tells you which one. * A bad schedule is rejected **whole**. Nothing is stored, and the message names the day. *** ## `GET` — read it ```bash theme={null} curl "https://app.tuco.ai/api/goal-bots/6aa9813105bb2cbf5931ac1f/reply-hours" \ -H "Authorization: Bearer tuco_xxxxxxxxxxxxx" ``` ### Success (`200 OK`) ```json theme={null} { "goalBotId": "6aa9813105bb2cbf5931ac1f", "name": "Auto Replies", "replyHours": { "days": { "mon": { "start": "09:00", "end": "17:00" } } }, "timezone": "America/New_York", "answeringNow": true, "reason": "inside", "localTime": "11:02", "localDay": "mon", "summary": "Monday, 09:00 to 17:00. Tuesday and Wednesday and Thursday and Friday and Saturday and Sunday, no replies." } ``` `answeringNow` and `reason` answer the question a script actually has before it does anything, so you do not have to re-implement the schedule logic yourself. | `reason` | meaning | | - | - | | `no_schedule` | no hours set — the bot answers always | | `inside` | inside today's window | | `outside` | today has a window, and now is not in it | | `day_off` | the bot does not answer today | | `override_on` | an override is forcing it to answer | | `override_off` | an override is forcing it silent | *** ## `PUT` — set it `PUT` **replaces** the whole schedule. It does not merge — send Monday to Friday and you get Monday to Friday, with no Saturday left over from last month. ```bash theme={null} curl -X PUT "https://app.tuco.ai/api/goal-bots/6aa9813105bb2cbf5931ac1f/reply-hours" \ -H "Authorization: Bearer tuco_xxxxxxxxxxxxx" \ -H "Content-Type: application/json" \ -d '{ "days": { "mon": { "start": "09:00", "end": "17:00" }, "tue": { "start": "09:00", "end": "17:00" }, "wed": { "start": "09:00", "end": "17:00" }, "thu": { "start": "09:00", "end": "17:00" }, "fri": { "start": "09:00", "end": "17:00" } } }' ``` Stop the bot now and keep the schedule for when you turn it back on: ```bash theme={null} curl -X PUT "https://app.tuco.ai/api/goal-bots/6aa9813105bb2cbf5931ac1f/reply-hours" \ -H "Authorization: Bearer tuco_xxxxxxxxxxxxx" \ -H "Content-Type: application/json" \ -d '{ "days": { "mon": { "start": "09:00", "end": "17:00" } }, "override": "off" }' ``` The body may be the schedule itself or wrapped as `{ "replyHours": { ... } }` — both read naturally, so both are accepted. ### Success (`200 OK`) ```json theme={null} { "ok": true, "goalBotId": "6aa9813105bb2cbf5931ac1f", "replyHours": { "days": { "mon": { "start": "09:00", "end": "17:00" } } }, "timezone": "America/New_York", "answeringNow": true, "reason": "inside", "summary": "Monday, 09:00 to 17:00. Tuesday and Wednesday and Thursday and Friday and Saturday and Sunday, no replies." } ``` *** ## `DELETE` — clear it The bot goes back to answering at all times. ```bash theme={null} curl -X DELETE "https://app.tuco.ai/api/goal-bots/6aa9813105bb2cbf5931ac1f/reply-hours" \ -H "Authorization: Bearer tuco_xxxxxxxxxxxxx" ``` `PUT` with a body of `null` or `{}` does the same thing. *** ## Errors A bad schedule is rejected whole, and the message names the day so you know which value to fix. ```json theme={null} { "error": "Saturday: the start time and the end time are the same. Set an end time that is not the start time.", "errors": ["Saturday: the start time and the end time are the same. Set an end time that is not the start time."] } ``` | Status | When | Body | | - | - | - | | `400` | `start` equal to `end` | `{{ "error": "Saturday: the start time and the end time are the same. Set an end time that is not the start time." }}` | | `400` | A time that is not `HH:MM` | `{{ "error": "Monday: the start time must look like 09:00." }}` | | `400` | A key that is not a day | `{{ "error": "\"funday\" is not a day. Use mon, tue, wed, thu, fri, sat or sun." }}` | | `400` | Malformed `{id}` | `{{ "error": "Invalid id" }}` | | `401` | Missing or invalid API key | `{{ "error": "Unauthorized" }}` | | `404` | No bot with that id in your workspace | `{{ "error": "Goal bot not found" }}` | *** ## Gotchas > [!WARNING] > > **Hours apply to the bot that ANSWERS, which is not always the bot you set them on.** Routing > happens first, hours second. A bot with an empty `includeTags` answers every lead **before** the > default "Auto Replies" bot does — so hours on the default bot do nothing in a workspace that also > has an untagged bot. Check which bot actually answers a lead before you schedule it. * **There is no workspace default.** Setting hours on one bot does nothing to the others. * **Instruction bots have no reply hours.** The older stage engine on `/api/instructions` is not covered, so "the AI stops at 17:00" is only true of goal bots. * A schedule stored with a broken window — backwards, or not `HH:MM` — makes the bot **answer**, not go silent. A bug must never be able to mute a bot that was working. # Rotate Webhook Secret Source: https://docs.tuco.ai/api-reference/endpoint/rotate-webhook-secret POST /api/webhooks/{id}/rotate-secret Replace a Tuco webhook's signing secret. The new secret is returned once; every delivery and replay after this is signed with it. Generates a new signing secret for the webhook and returns it **once**. Every delivery from now on, including [replays](/api-reference/endpoint/replay-webhook-delivery), is signed with the new secret. Update your endpoint's verification before rotating, or accept both secrets for a short overlap. ## Authentication ```bash theme={null} Authorization: Bearer tuco_xxxxxxxxxxxxx ``` ## Path parameters **id** `string` *required* Webhook ID. ## Response **id** `string` Webhook ID. **secret** `string` The new secret. Store it now; it is never shown again. **warning** `string` Reminder that the secret is shown once. | Status | When | | - | - | | `200` | Rotated | | `401` | Missing or invalid API key | | `402` | Workspace is read-only (billing) | | `404` | Webhook not found in your workspace | ## Example ```bash theme={null} curl -X POST "https://app.tuco.ai/api/webhooks/680a1b2c3d4e5f6789012345/rotate-secret" \ -H "Authorization: Bearer tuco_xxxxxxxxxxxxx" ``` ```json theme={null} { "id": "680a1b2c3d4e5f6789012345", "secret": "q1Vb3m8YqGv0pX7nKc2Zr5tLw9EaHd4JfU6sNyB0iOk=", "warning": "Save this secret now. You will not be able to see it again." } ``` # Create or Update API Tool Source: https://docs.tuco.ai/api-reference/endpoint/save-tool POST /api/campaign-tools Create or update a custom API tool in Tuco AI — define name, HTTP method, URL, headers, and JSON schema so goal bots can call your endpoint. > [!NOTE] > > An API tool lets a goal bot call **your** endpoint mid-conversation — check stock, look up an > order, fetch a balance — and use the answer in its reply. Attach a tool to a bot by putting its > `_id` in that bot's `allowedToolIds`. One endpoint does both jobs. **Omit `id` to create; pass `id` to update** that tool in place. ## Authentication Pass your workspace API key as a Bearer token, or use a Clerk session token. ```bash theme={null} Authorization: Bearer tuco_xxxxxxxxxxxxx ``` *** ## Request body **id** `string` Omit to create a new tool. Pass an existing tool `_id` to update it — every other field is overwritten with what you send, so send the complete tool. **name** `string` *required* Tool name. Also derives `variableKey` (the variable a bot reads the result from), so keep it short and snake\_case — `check_stock` becomes `api_check_stock`. A blank name returns `400 Tool name is required`. **url** `string` *required* The endpoint Tuco calls. Must be a reachable public URL — private, local and blocked hosts return `400 Tool URL is invalid or blocked`. **responseMapping** `string` *required* Dot path into your response that becomes the tool's value, e.g. `data.quantity`. Blank returns `400 Response mapping is required`. **method** `string` (default: GET) One of `GET`, `POST`, `PUT`, `PATCH`, `DELETE`. **Any other value silently falls back to `GET`** — read `method` back from the response to confirm. **description** `string` What the tool does. The model reads this when deciding whether to call it, so write it for the model, not for a human changelog. **headers** `object` Flat object of header name → value, e.g. `{ "Authorization": "Bearer abc123" }`. Non-string values and blank names are dropped. **body** `string` Request body template sent with `POST`/`PUT`/`PATCH`. A **string**, not an object. Lead fields can be interpolated into it. *** ## Example — create ```bash theme={null} curl -X POST "https://app.tuco.ai/api/campaign-tools" \ -H "Authorization: Bearer tuco_xxxxxxxxxxxxx" \ -H "Content-Type: application/json" \ -d '{ "name": "check_stock", "method": "GET", "url": "https://api.example.com/stock", "responseMapping": "data.quantity", "description": "Returns current stock for a SKU" }' ``` ## Example — update ```bash theme={null} curl -X POST "https://app.tuco.ai/api/campaign-tools" \ -H "Authorization: Bearer tuco_xxxxxxxxxxxxx" \ -H "Content-Type: application/json" \ -d '{ "id": "6ac3ed9271adb32c88d566e0", "name": "check_stock", "method": "GET", "url": "https://api.example.com/v2/stock", "responseMapping": "data.quantity" }' ``` ### Success (`200 OK`) ```json theme={null} { "tool": { "_id": "6ac3ed9271adb32c88d566e0", "workspaceId": "org_3CzFir0Fps4hHL4nbU9WQ6FR4ur", "name": "check_stock", "description": "Returns current stock for a SKU", "method": "GET", "url": "https://api.example.com/stock", "responseMapping": "data.quantity", "variableKey": "api_check_stock", "createdAt": "2026-10-05T18:33:54.781Z", "updatedAt": "2026-10-05T18:33:54.781Z" } } ``` > [!TIP] > > Run it once with [`POST /api/campaign-tools/test`](/api-reference/endpoint/test-tool) before you > attach it to a bot — that returns the live response and the mapped value. *** ## Errors | Status | When | Body | | - | - | - | | `400` | `name` blank | `{ "error": "Tool name is required" }` | | `400` | `url` blank | `{ "error": "Tool URL is required" }` | | `400` | `url` not reachable or on a blocked host | `{ "error": "Tool URL is invalid or blocked" }` | | `400` | `responseMapping` blank | `{ "error": "Response mapping is required" }` | | `400` | `id` supplied but malformed | `{ "error": "Invalid tool id" }` | | `401` | Missing or invalid API key | `{ "error": "Unauthorized" }` | | `404` | `id` supplied but no such tool in your workspace | `{ "error": "Tool not found" }` | # Send Drip Source: https://docs.tuco.ai/api-reference/endpoint/send-drip POST /api/drip Same body as POST /api/messages, built for bulk/bursty CRM enrollment fan-out — never 429s, fast-acks 202, drips out safely per line. Bearer-token auth, JSON. > [!WARNING] > > **The Try it panel runs against production** (`https://app.tuco.ai`) with the key you paste > into it. There is no sandbox — a request from this page queues a real message from one of your lines. > [!NOTE] > > Use this instead of [`POST /api/messages`](/api-reference/endpoint/send-message) > for **bulk** sends (HubSpot/CRM parallel enrollment, list blasts). **Same request > body — change only the URL.** It never `429`s a blast, acks `202` immediately, and > drips the sends out safely per line. Full guide: [Drip](/api-reference/drip). ## Authentication Pass your workspace API key as a Bearer token (same key as `/api/messages`). ```bash theme={null} Authorization: Bearer tuco_xxxxxxxxxxxxx ``` *** ## Request body Identical to [`POST /api/messages`](/api-reference/endpoint/send-message) — the fields below are the ones a bulk enrolment actually uses. Everything else that endpoint accepts works here too. **message** `string` The text to send. Required unless `attachmentUrls` is provided. **Send the finished text** — merge fields are not substituted here. A body still containing `{{firstName}}` is rejected with `400 MALFORMED_NAME_TEMPLATE`. **recipientPhone** `string` **The phone number to text, in E.164 format** (e.g. `"+14155551234"`). This is how you address a drip send. Required unless you pass `recipientEmail`. **recipientEmail** `string` Only for `messageType: "email"`, or an Apple ID you already know is reachable. Prefer `recipientPhone`. Required unless you pass `recipientPhone`. **messageType** `string` (default: imessage) `imessage`, `sms` or `email`. Anything else returns `400 Invalid messageType. Must be email, sms, or imessage`. **attachmentUrls** `string[]` Public URLs to attach. Only `http`/`https` entries are kept. When present, `message` may be empty. **voiceNote** `boolean` (default: false) Deliver a single audio attachment as a native iMessage voice note. **fromLineId** `string` Pin the sending line. Omit to round-robin across the workspace's active lines. **correlationId** `string` Your own id for this send, echoed back in the `202` and in every webhook. Also accepted as the `x-correlation-id` header, which wins. Omit and Tuco generates one (`drip_…`). **timezone** `string` IANA timezone for the send window, e.g. `"America/New_York"`. Required if you set a window. **sendWindowStart** `string` Earliest send time, `HH:mm`. Must be `HH:mm` or the request returns `400 Invalid time format`. **sendWindowEnd** `string` Latest send time, `HH:mm`. **allowedDaysOfWeek** `number[]` Days sending is allowed. `0` = Sunday, `6` = Saturday. **hsContactId** `string` HubSpot contact id, for linking the send back to the CRM record. **hsPortalId** `string` HubSpot portal id. **ghlContactId** `string` GoHighLevel contact id. **ghlLocationId** `string` GoHighLevel location id. *** ## Example ```bash theme={null} curl -X POST "https://app.tuco.ai/api/drip" \ -H "Authorization: Bearer tuco_xxxxxxxxxxxxx" \ -H "Content-Type: application/json" \ -H "Idempotency-Key: hs-enroll-8471-step2" \ -d '{ "message": "Hi Jane — following up on your quote.", "recipientPhone": "+14155551234", "hsContactId": "8471", "hsPortalId": "1234567" }' ``` ### Success (`202 Accepted`) ```json theme={null} { "status": "queued", "correlationId": "drip_1791225101362_7vvdij", "scheduledDate": "2026-10-05T18:31:44.089Z", "jitterMs": 2727 } ``` *** ## Errors | Status | When | Body | | - | - | - | | `400` | `message` and `attachmentUrls` both empty | `{ "error": "Message and attachmentUrls cannot both be empty" }` | | `400` | No `recipientPhone` or `recipientEmail` | `{ "error": "Either recipientEmail or recipientPhone is required." }` | | `400` | `recipientPhone` is not a valid number | `{ "error": "Invalid recipientPhone format..." }` | | `400` | Invalid `messageType` | `{ "error": "Invalid messageType. Must be email, sms, or imessage" }` | | `400` | `message` still contains a merge field | `{ "error": "Malformed message...", "code": "MALFORMED_NAME_TEMPLATE" }` | | `400` | Bad time window or timezone | `{ "error": "Invalid time format..." }` | | `400` | Body is not a JSON object | `{ "error": "Request body must be a JSON object" }` | | `401` | Missing or invalid API key | `{ "error": "Unauthorized" }` | *** ## How it differs from `/api/messages` * **Not rate-limited** — exempt from the 60/min send limit; a bulk blast is never rejected. * **Always `202`** — the request is buffered and the message is created a moment later, then sent still later (paced per line by the ban protector: \~7 new/hr, \~50 new/day, 150 total/day). * **Response is `202 { status, correlationId, scheduledDate, jitterMs }`** — no `messageId` (the message doesn't exist yet at ack time); use `correlationId` to correlate in your webhooks. * **`Idempotency-Key`** header is honored (HubSpot retries return the first ack). > [!TIP] > > For **low-volume, send-now** traffic where you want the real delivery status back > immediately, use [`POST /api/messages`](/api-reference/endpoint/send-message) > instead. # Send to a Group Chat Source: https://docs.tuco.ai/api-reference/endpoint/send-group-message POST /api/unibox/send-group Send text, files or a voice note into an iMessage group chat your Tuco line is already in. Tuco can't start new groups. Bearer-token auth, JSON. > [!NOTE] > > You can only send into a group your line is **already in**. Someone else creates the > group and adds your line. Tuco cannot start a new group. ## What this endpoint does It sends one message into an existing iMessage group chat: * text * up to 2 files (photo, video, PDF, document, audio) * or a native voice note (the waveform bubble) A group is not a lead. Compared with a 1:1 send: | | 1:1 send (`/api/messages`) | Group send (this endpoint) | | - | - | - | | Who it goes to | One lead | Everyone in the group | | Lead / campaign / CRM sync | Yes | No | | SMS fallback | Yes | No | | Daily / new-conversation limits | Yes | No | | Webhooks | `message.*` | [`group.message.*`](/api-reference/message-webhooks#group-chat-events) | ## Authentication Pass your workspace API key as a Bearer token. ```bash theme={null} Authorization: Bearer tuco_xxxxxxxxxxxxx ``` *** ## Step 1 — find the group's `conversationId` List your conversations. Groups have `"isGroup": true`. See [List Conversations](/api-reference/endpoint/conversations#group-chats). ```bash theme={null} curl "https://app.tuco.ai/api/unibox/conversations?limit=50&messageLimit=1" \ -H "Authorization: Bearer tuco_xxxxxxxxxxxxx" ``` A group in the response: ```json theme={null} { "id": "group:iMessage;+;chat606535035660201399", "isGroup": true, "recipientName": "Alex · +13025550100, Sam · sam@example.com", "groupMembers": [ { "address": "+13025550100", "name": "Alex" }, { "address": "sam@example.com", "name": "Sam" } ] } ``` The `id` (it starts with `group:`) is the `conversationId` you send to. *** ## Step 2 — send ### Request body **conversationId** `string` *required* The group's `id` from Step 1, for example `group:iMessage;+;chat606535035660201399`. **message** `string` The text. Up to 5,000 characters. Optional when you send a file. **attachmentUrls** `string[]` Up to 2 public `https://` file URLs. **attachmentNames** `string[]` File names, in the same order as `attachmentUrls`. Optional. Defaults to the file name in the URL. **voiceNote** `boolean` (default: false) `true` sends one audio file as a native iMessage voice note. Send exactly one audio URL in `attachmentUrls` (MP3, M4A, WAV, AAC, OGG, OPUS, FLAC, AIFF, AMR or CAF). Tuco converts it for you. Needs a line that supports native voice notes. See [voice note requirements](/api-reference/endpoint/send-with-attachments#voice-note-requirements). You must send `message`, a file, or both. ### Examples ```bash Text theme={null} curl -X POST "https://app.tuco.ai/api/unibox/send-group" \ -H "Authorization: Bearer tuco_xxxxxxxxxxxxx" \ -H "Content-Type: application/json" \ -d '{ "conversationId": "group:iMessage;+;chat606535035660201399", "message": "Hi all, sharing the deck now" }' ``` ```bash Text + file theme={null} curl -X POST "https://app.tuco.ai/api/unibox/send-group" \ -H "Authorization: Bearer tuco_xxxxxxxxxxxxx" \ -H "Content-Type: application/json" \ -d '{ "conversationId": "group:iMessage;+;chat606535035660201399", "message": "Here is the deck", "attachmentUrls": ["https://example.com/files/deck.pdf"], "attachmentNames": ["deck.pdf"] }' ``` ```bash Voice note theme={null} curl -X POST "https://app.tuco.ai/api/unibox/send-group" \ -H "Authorization: Bearer tuco_xxxxxxxxxxxxx" \ -H "Content-Type: application/json" \ -d '{ "conversationId": "group:iMessage;+;chat606535035660201399", "attachmentUrls": ["https://example.com/audio/hello.m4a"], "voiceNote": true }' ``` Text and files arrive in this order: the text first, then each file as its own bubble. *** ## Response ### Text or files — `200 OK` Sent right away. `200` means your line accepted every part. ```json theme={null} { "success": true, "messageId": "6aedeb65fa7ac0d2e5e221d5", "message": { "_id": "6aedeb65fa7ac0d2e5e221d5", "direction": "sent", "status": "sent", "message": "Hi all, sharing the deck now", "isGroupChat": true, "groupChatGuid": "iMessage;+;chat606535035660201399", "externalMessageId": "626E6E86-…" } } ``` ### Voice note — `200 OK` A voice note is queued and answered at once, the same as a 1:1 voice note. It usually arrives within a few seconds. If you also sent `message`, the text goes first as its own message, and its id is in `textMessageId`. ```json theme={null} { "success": true, "messageId": "6aedeb5cfa7ac0d2e5e221cc", "status": "sent", "fastAck": true, "textMessageId": "6aedeb5bfa7ac0d2e5e221cf", "message": { "_id": "6aedeb5cfa7ac0d2e5e221cc", "voiceNote": true, "isGroupChat": true } } ``` ### Errors | Status | When | Body | | - | - | - | | `400` | `conversationId` is not a group id | `{ "error": "Not a group conversation" }` | | `400` | No text and no file | `{ "error": "Message is empty" }` | | `400` | Text over 5,000 characters | `{ "error": "Message is too long (max 5000 characters)" }` | | `400` | More than 2 files | `{ "error": "Up to 2 attachments per message" }` | | `400` | A file URL is not `https://` | `{ "error": "Attachment URL must be https" }` | | `400` | `voiceNote: true` with no file | `{ "code": "VOICE_NOTE_NO_ATTACHMENT", "error": "..." }` | | `400` | `voiceNote: true` and a file is not audio | `{ "code": "VOICE_NOTE_NOT_AUDIO", "error": "..." }` | | `400` | `voiceNote: true` with more than one recording | `{ "code": "VOICE_NOTE_INVALID", "error": "..." }` | | `400` | `voiceNote: true` on a line that can't send native voice notes | `{ "code": "VOICE_NOTE_NO_PRIVATE_API", "error": "..." }` | | `401` | Missing or invalid API key | `{ "error": "Unauthorized" }` | | `404` | No group with this id in your workspace | `{ "error": "Group conversation not found" }` | | `409` | The line in this group is no longer in your workspace | `{ "error": "The line in this group is no longer in your workspace" }` | | `502` | Your line rejected the send | `{ "success": false, "error": "...", "messageId": "..." }` | | `502` | The text went out but a file failed | `{ "success": false, "error": "Text sent, but 1 attachment(s) failed — ...", "messageId": "..." }` | | `503` | The voice note could not be queued | `{ "success": false, "error": "Could not queue the voice note. Try again." }` | | `504` | Your line did not answer in time | `{ "success": false, "error": "...", "messageId": "..." }` | > [!WARNING] > > On `502` or `504`, part of the message may already be in the group. Read the > thread (below) before you resend, or everyone in the group gets it twice. > If a timed-out message does arrive, Tuco flips it to `sent` on its own. *** ## Read the group thread Pass the group id as `conversation`. **URL-encode it.** The id contains `;` and `+`, and an unencoded `+` turns into a space, so the group is silently not found. ```bash theme={null} curl -G "https://app.tuco.ai/api/unibox/conversations" \ -H "Authorization: Bearer tuco_xxxxxxxxxxxxx" \ --data-urlencode "conversation=group:iMessage;+;chat606535035660201399" ``` The group is in `conversations` if it is on the page you asked for. Otherwise it comes back as `preselectedConversation`. Each received message has `groupSenderAddress` (the member who sent it). ```json theme={null} { "_id": "6aecdec997d47c708109eb9c", "direction": "received", "message": "Cool video came", "isGroupChat": true, "groupChatGuid": "iMessage;+;chat606535035660201399", "groupSenderAddress": "sam@example.com" } ``` *** ## From the MCP The MCP's `send-reply` tool sends into a group too. Pass the group's id as `conversationId` (find it with `list-conversations`, `isGroup: true`). `POST /api/unibox/send-reply` with a `group:…` id does the same as this endpoint. ## What else works in a group | Action | Works? | How | | - | - | - | | React (tapback) | Yes | [Send Reaction](/api-reference/endpoint/send-reaction) with the group message's `_id` | | Typing indicator | No | Returns `400` for a group message | | Webhooks | Yes | Subscribe to [`group.message.*`](/api-reference/message-webhooks#group-chat-events): received, sent, failed, reaction | | Create a group, add or remove members | No | Someone in the group does this from their phone | # Send Message Source: https://docs.tuco.ai/api-reference/endpoint/send-message POST /api/messages Send an iMessage, SMS, or email to a contact — the core automation endpoint. REST endpoint in the Tuco AI iMessage API — bearer-token auth, JSON. > [!WARNING] > > **The Try it panel runs against production** (`https://app.tuco.ai`) with the key you paste > into it. There is no sandbox — a request from this page sends a real message from one of your lines. > [!NOTE] > > This is the primary endpoint for automation tools like **GetSales**, **n8n**, **Make**, or your own backend. > One call = one message. Tuco handles retries, delivery verification, and fallback internally. ```bash Minimal theme={null} curl -X POST "https://app.tuco.ai/api/messages" \ -H "Authorization: Bearer tuco_xxxxxxxxxxxxx" \ -H "Content-Type: application/json" \ -d '{ "message": "Hi from Tuco.", "recipientPhone": "+12025551234" }' ``` ```bash Send window, weekdays theme={null} curl -X POST "https://app.tuco.ai/api/messages" \ -H "Authorization: Bearer tuco_xxxxxxxxxxxxx" \ -H "Content-Type: application/json" \ -d '{ "message": "Morning! Quick question about your quote.", "recipientPhone": "+12025551234", "sendWindowStart": "09:00", "sendWindowEnd": "18:00", "timezone": "America/New_York", "allowedDaysOfWeek": [1, 2, 3, 4, 5] }' ``` ```bash Follow-up, keep the gap theme={null} curl -X POST "https://app.tuco.ai/api/messages" \ -H "Authorization: Bearer tuco_xxxxxxxxxxxxx" \ -H "Content-Type: application/json" \ -d '{ "message": "Just checking you saw my last note", "recipientPhone": "+12025551234", "respectGap": true }' ``` ```bash Gap + skip if replied theme={null} curl -X POST "https://app.tuco.ai/api/messages" \ -H "Authorization: Bearer tuco_xxxxxxxxxxxxx" \ -H "Content-Type: application/json" \ -d '{ "message": "Still interested? Happy to hold your slot.", "recipientPhone": "+12025551234", "respectGap": true, "skipIfReplied": true, "sendWindowStart": "09:00", "sendWindowEnd": "18:00", "timezone": "America/New_York" }' ``` ```json 201 Sent theme={null} { "success": true, "status": "sent", "leadId": "69b2c41d352a78479d2c623b", "message": { "_id": "69b344bc6dae1d942ece4d0e", "message": "Hi from Tuco.", "messageType": "imessage", "direction": "sent", "recipientPhone": "+12025551234", "fromLineId": "69ab427ac1feb77d7f46462e", "leadId": "69b2c41d352a78479d2c623b", "status": "sent", "createdAt": "2026-10-13T16:57:58.468Z", "updatedAt": "2026-10-13T16:58:00.016Z", "sentAt": "2026-10-13T16:58:00.016Z" } } ``` ```json 201 Held theme={null} { "success": true, "status": "scheduled", "leadId": "6ace9f58e350b3be067aef80", "message": { "_id": "6ace9f59e350b3be067aef81", "message": "Morning! Quick question about your quote.", "messageType": "imessage", "direction": "sent", "recipientPhone": "+12025551234", "fromLineId": "6ace9f5622264a6eecd4b333", "leadId": "6ace9f58e350b3be067aef80", "status": "scheduled", "scheduledDate": "2026-10-14T13:00:00.000Z", "settings": { "timezone": "America/New_York", "sendWindowStart": "09:00", "sendWindowEnd": "18:00", "allowedDaysOfWeek": [1, 2, 3, 4, 5] }, "createdAt": "2026-10-13T23:15:05.519Z", "updatedAt": "2026-10-13T23:15:05.771Z" } } ``` ```json 200 Skipped theme={null} { "success": true, "skippedOnly": true, "skipReason": "recipient_replied", "skipMessage": "Skipped: this contact already replied in your workspace at any time. The skipIfReplied gate prevented this send.", "repliedAt": "2026-10-13T16:59:48.131Z", "message": null, "leadId": "6ace637e30e2d7468c7bf397" } ``` ```json 400 Window theme={null} { "error": "sendWindowStart must be earlier than sendWindowEnd. Overnight windows (e.g. \"22:00\"–\"06:00\") are not supported; use \"00:00\"–\"23:59\" to send at any hour.", "code": "INVALID_SEND_WINDOW" } ``` ```json 400 Timezone theme={null} { "error": "\"EST\" is an abbreviation with a fixed offset that ignores daylight saving. Use an IANA timezone name such as \"America/New_York\" or \"Europe/London\", or omit timezone to use your workspace timezone.", "code": "INVALID_TIMEZONE" } ``` ```json 400 Days theme={null} { "error": "allowedDaysOfWeek must be an array of whole numbers from 0 (Sunday) to 6 (Saturday), e.g. [1,2,3,4,5].", "code": "INVALID_ALLOWED_DAYS" } ``` ## Authentication Pass your workspace API key as a Bearer token, or use a Clerk session token. ```bash theme={null} Authorization: Bearer tuco_xxxxxxxxxxxxx ``` *** ## Request body **message** `string` The text content to send. **Required unless** `attachmentUrls` is provided (you can send attachments only, or message + attachments). **Template variables** are filled in **at send time** — on every send attempt, against the line that actually sends the message (so retries, scheduled or send-window-deferred messages, and round-robin all name the right line) and the contact's current data. The same variables campaigns use: | Variable | Filled with | | - | - | | `{line_first_name}` | First name of the sending line | | `{line_name}` | Sending line's first + last name | | `{line_email}` · `{line_phone}` | Sending line's email · phone | | `{firstName}` `{lastName}` `{companyName}` `{email}` `{phone}` `{jobTitle}` `{notes}` | The contact's fields | | `{cf:Field Name}` | A contact custom field | | `{yourVariable}` | Your workspace variable's default (Settings → Variables) | Single `{x}` or double `{{x}}` braces, any case. Add a fallback after a pipe: `{firstName|there}`. Variables work inside links too (`https://cal.com/{line_first_name}`). Anything in braces that is **not** one of these is sent exactly as written. **A blank is never sent.** If a variable has no value and no fallback, the request is rejected: an empty `{firstName}` / `{lastName}` → `400 MALFORMED_NAME_TEMPLATE`; any other → `400 TEMPLATE_VARIABLE_UNRESOLVED` (the response lists them in `unresolvedVariables`). Text you already filled in yourself is unaffected; an unfilled token from another tool (e.g. `{{contact_name}}`, `{name}`) or a greeting whose name expanded to nothing (`"Hey , …"`) is still rejected with `MALFORMED_NAME_TEMPLATE`. ```json theme={null} { "recipientPhone": "+14155550123", "message": "Hey {firstName|there}, {line_first_name} here — grab a time: https://cal.com/{line_first_name}" } ``` **attachmentUrls** `string[]` Optional array of URLs (max 2, max 25 MB each). When provided, `message` can be empty. Supported formats: images (PNG, JPG, GIF, WebP, HEIC), video (MP4, MOV), audio (MP3, M4A, WAV, AAC, OGG, CAF), and PDF. Supported sources: any public URL, UploadThing/Blob URLs that belong to your workspace. To send audio as a native iMessage voice note (the waveform bubble), add `voiceNote: true`. The audio must be a **direct, publicly reachable file URL** — a YouTube or Drive page is rejected with a 400. Easiest source is **Leads → Uploads** (`/leads?tab=uploads`). See [Voice note requirements](/api-reference/endpoint/send-with-attachments#voice-note-requirements). With an attachment or voice note, you get `status: "sent"` right away and it starts sending. If it fails, you get a `message.failed` webhook for the same `message._id`. > [!TIP] > > Sending the same attachment URL repeatedly (e.g. a promo video in an automation)? Tuco caches attachments per line — the second send skips the download and upload, making it significantly faster. **attachmentNames** `string[]` Optional display names for the attachments, aligned 1:1 with `attachmentUrls`. Omit and Tuco uses the filename from the URL. **voiceNote** `boolean` (default: false) Send a single audio attachment as a **native iMessage voice note** (the waveform bubble) instead of a generic audio file. Tuco transcodes the audio for you. Requires exactly one audio attachment in `attachmentUrls` — see [Send with Attachments](/api-reference/endpoint/send-with-attachments#voice-note-requirements) for the full rules. **recipientPhone** `string` **The phone number to text, in E.164 format** (e.g. `"+12025551234"`). This is how you address almost every send — you do not need a `leadId`. Tuco matches an existing lead on this number, or creates one under the **Quick Sends** list. Required unless you pass `leadId` or `recipientEmail`. **leadId** `string` Send to an existing lead using their stored contact details. When provided together with `recipientPhone`, the body's phone number is the send-to address and the lead is used for linking. Required unless you pass `recipientPhone` or `recipientEmail`. **recipientEmail** `string` > [!WARNING] > > **Use `recipientPhone` unless you specifically need this.** An email address only reaches someone > over iMessage if that exact address is registered to their Apple account, which is uncommon and > impossible to assume. Addressing by phone number is what works. Only useful in two cases: `messageType: "email"`, or iMessage to a contact you already know is reachable at that Apple ID. Required unless you pass `recipientPhone` or `leadId`. **messageType** `string` (default: imessage) Channel to use. When omitted, defaults to `"imessage"`. | Value | Channel | Addresses tried (from lead) | | - | - | - | | `"imessage"` | iMessage via device relay | phone → altPhone1-3 → email → altEmail1-3 | | `"sms"` | SMS via Twilio | phone → altPhone1-3 only | | `"email"` | Email | email → altEmail1-3 only | **fromLineId** `string` Tuco line ID to send from. **Optional** — when omitted, Tuco round-robins across your workspace's active lines automatically. **recipientName** `string` Display name for the recipient. Derived from the lead when omitted. ### Alternate contact fields Stored on the lead (created or found). The worker tries these in priority order when the primary address fails iMessage availability. **altPhone1** `string` Alternate phone number 1 **altPhone2** `string` Alternate phone number 2 **altPhone3** `string` Alternate phone number 3 **altEmail1** `string` Alternate email 1 **altEmail2** `string` Alternate email 2 **altEmail3** `string` Alternate email 3 ### Scheduling & time window Control **when** the message is sent. All fields are optional. When omitted, the message sends immediately (subject to line limits and device gaps). **scheduledDate** `string` ISO 8601 timestamp to send in the future (e.g. `"2026-10-15T14:30:00Z"`). The response `status` is `"scheduled"`. If you also set a send window and this time falls outside it, the message is moved to the next time the window is open. A value that can't be parsed returns `400`. **sendWindowStart** `string` Earliest time to send, `HH:mm` 24-hour format (e.g. `"09:00"`), inclusive. Set **both** `sendWindowStart` and `sendWindowEnd` — if only one is sent, the window is ignored. Outside the window the request still returns `201` with `status: "scheduled"`; the message is held until the window opens. Use `"00:00"`–`"23:59"` for any hour. Anything that isn't `HH:mm` returns `400`. **sendWindowEnd** `string` Latest time to send, `HH:mm` (e.g. `"17:00"`). The end is exclusive, and it must be later than the start. An overnight window such as `"22:00"`–`"06:00"` returns `400 INVALID_SEND_WINDOW`; use `"00:00"`–`"23:59"` to send at any hour. **timezone** `string` IANA timezone for the send window (e.g. `"America/New_York"`). **Optional.** When omitted, your workspace timezone is used (or `America/New_York` if the workspace has none). Use a full name — an abbreviation like `"EST"` or an unknown name returns `400 INVALID_TIMEZONE` when a send window is set. `"UTC"` is accepted. The timezone is only used together with a send window. **allowedDaysOfWeek** `number[]` Days when sending is allowed, as whole numbers. `0` = Sunday, `6` = Saturday. Example: `[1,2,3,4,5]` for weekdays only. An empty array means every day; any other value returns `400 INVALID_ALLOWED_DAYS`. **Only applies together with `sendWindowStart` and `sendWindowEnd`** — a day list without hours is ignored. On a day that isn't allowed, the message waits for `sendWindowStart` on the next allowed day. See [Send window and allowed days](#send-window-and-allowed-days). **respectGap** `boolean` (default: false) Keep the wait between follow-ups to the same contact. When `true`, and an earlier message to this contact went out late, this message is held so the original spacing is preserved: it waits until the previous message's actual send time plus the gap between your two API calls. Works on its own — no send window or workspace setting needed. Accepts `true` or `"true"`; any other value is treated as `false`. While held, the response `status` is `"scheduled"`. See [Keep the wait between follow-ups](#keep-the-wait-between-follow-ups). ### Fallback & advanced **sendFallbackSmsOnFailed** `boolean` (default: false) When `true`, if the message ends in `failed` status (technical error after retries), Tuco sends a fallback SMS via your configured fallback number. If no fallback is configured on the workspace the request is **still accepted** — the iMessage send proceeds and simply has no SMS to fall back to. Check [`GET /api/workspace/fallback-config`](/api-reference/endpoint/fallback-config) first if you need the fallback to actually fire. **forceFallback** `boolean` (default: false) When `true`, Tuco **skips the iMessage availability check entirely** and sends the message straight via your workspace's configured fallback — Twilio, GHL, or a custom webhook (Settings → *When iMessage isn't available*). Use it when you already know the recipient isn't on iMessage, or you simply want SMS. The send never touches iMessage, so it does **not** consume the line's daily cap or the availability-check budget, and the response status is `"fallback"`. If no fallback is configured — or the fallback dispatch fails (e.g. a bad Twilio from-number) — the message is **not** delivered: the response returns `"success": false` with a channel-tagged `error`, and the message is recorded with `"fallbackSmsStatus": "failed"`. The request itself still succeeds — read the `success` flag in the body rather than relying on the status code. Unlike `sendFallbackSmsOnFailed` (which is *reactive* — fallback only after an iMessage send fails), `forceFallback` is *proactive*: it never attempts iMessage in the first place. **skipIfReplied** `string | boolean` (default: false) Workspace-level reply gate. When set, Tuco **suppresses this send if the contact has already replied in your workspace**. * `false` / `"false"` / omitted → always send (default, backward compatible) * `true` / `"true"` → skip if the contact has **ever** replied * a window string → skip only if they replied **within** that window: `"1m"`, `"1h"`, `"1d"`, `"2d"`, `"5d"`, `"7d"`, `"14d"`, `"1mo"`, `"1yr"` (`m`=minute, `h`=hour, `d`=day, `w`=week, `mo`=30 days, `yr`=365 days) Scope is your **workspace** — a reply to *any* of your lines counts (not just the sending line). The check never crosses workspaces. On a skip, **no message is created** and the API returns `200` with `skippedOnly: true` (see [Skip if the contact already replied](#skip-if-the-contact-already-replied)). The check runs again right before a queued message sends: if the contact replied while it was waiting, it is cancelled instead of sent. An unrecognized value returns `400 INVALID_SKIP_IF_REPLIED`. **batchId** `string` Free-form string to group related messages for reporting. **correlationId** `string` Optional tracing ID. If omitted, Tuco generates one (`app_…`). The same ID is preferred from the `x-correlation-id` request header. It flows through every internal log event for this send so you can grep one ID and see the entire request → gate → send → webhook chain. See [API Overview → Correlation IDs](/api-reference/introduction#correlation-ids-request-tracing). > [accordion] Request headers > > Headers Tuco recognizes in addition to `Authorization`. > > | Header | Purpose | > | - | - | > | `x-correlation-id` | Request-scoped tracing ID (preferred over body field). Echoed back in logs under `correlationId`. | > | `x-execution-id` | GHL workflow execution ID. Only set when calling from a GHL workflow context. | > | `x-ghl-workflow-id` | GHL workflow definition ID. Pairs with `x-execution-id`. | > | `Idempotency-Key` | When supplied, Tuco caches the response and replays it on retry within the idempotency window. Use one unique key per logical send. | *** ## Examples Create or import a lead first using [`POST /api/leads`](https://docs.tuco.ai/api-reference/leads), then send using `leadId` as shown below. ```bash Minimal using leadId (defaults to iMessage) theme={null} curl -X POST "https://app.tuco.ai/api/messages" \ -H "Authorization: Bearer tuco_xxxxxxxxxxxxx" \ -H "Content-Type: application/json" \ -d '{ "message": "Hi, this is a test from Tuco.", "leadId": "667f1f77bcf86cd799439012" }' ``` Need a `leadId` first? Create one with [`POST /api/leads`](https://docs.tuco.ai/api-reference/leads), then use the returned `leadId` in this request. ```bash HubSpot lead theme={null} curl -X POST "https://app.tuco.ai/api/messages" \ -H "Authorization: Bearer tuco_xxxxxxxxxxxxx" \ -H "Content-Type: application/json" \ -d '{ "message": "Hi from Tuco.", "leadId": "667f1f77bcf86cd799439013", "hsContactId": "120001", "hsPortalId": "991001" }' ``` ```bash GHL lead theme={null} curl -X POST "https://app.tuco.ai/api/messages" \ -H "Authorization: Bearer tuco_xxxxxxxxxxxxx" \ -H "Content-Type: application/json" \ -d '{ "message": "Hi from Tuco.", "leadId": "667f1f77bcf86cd799439014", "ghlContactId": "ghl_contact_001", "ghlLocationId": "eL7DD22BdZ0rismu7qCA" }' ``` ```bash With attachments theme={null} curl -X POST "https://app.tuco.ai/api/messages" \ -H "Authorization: Bearer tuco_xxxxxxxxxxxxx" \ -H "Content-Type: application/json" \ -d '{ "message": "Here is the file.", "leadId": "667f1f77bcf86cd799439012", "attachmentUrls": ["https://example.com/doc.pdf"] }' ``` ```bash GoHighLevel webhook (raw payload) theme={null} # The exact body GoHighLevel's "Webhook" workflow action posts. You only fill in # customData.message — Tuco derives the recipient + GHL identity from the rest. curl -X POST "https://app.tuco.ai/api/messages" \ -H "Authorization: Bearer tuco_xxxxxxxxxxxxx" \ -H "Content-Type: application/json" \ -d '{ "contact_id": "KWqc16yBbIV7hLfiRTse", "full_name": "Matheus Maia", "email": "alex@example.com", "phone": "+13055550100", "location": { "id": "57m52yUR4RkI2k1VuHhL" }, "customData": { "message": "Hi Matheus" } }' ``` ```bash Send window, weekdays only theme={null} curl -X POST "https://app.tuco.ai/api/messages" \ -H "Authorization: Bearer tuco_xxxxxxxxxxxxx" \ -H "Content-Type: application/json" \ -d '{ "message": "Morning! Quick question about your quote.", "recipientPhone": "+12025551234", "sendWindowStart": "09:00", "sendWindowEnd": "18:00", "timezone": "America/New_York", "allowedDaysOfWeek": [1, 2, 3, 4, 5] }' ``` ```bash Follow-up that keeps its gap theme={null} curl -X POST "https://app.tuco.ai/api/messages" \ -H "Authorization: Bearer tuco_xxxxxxxxxxxxx" \ -H "Content-Type: application/json" \ -d '{ "message": "Just checking you saw my last note", "recipientPhone": "+12025551234", "respectGap": true }' ``` ```bash Follow-up: keep the gap, skip if they replied theme={null} curl -X POST "https://app.tuco.ai/api/messages" \ -H "Authorization: Bearer tuco_xxxxxxxxxxxxx" \ -H "Content-Type: application/json" \ -d '{ "message": "Still interested? Happy to hold your slot.", "recipientPhone": "+12025551234", "respectGap": true, "skipIfReplied": true, "sendWindowStart": "09:00", "sendWindowEnd": "18:00", "timezone": "America/New_York" }' ``` *** ## Send straight from a GoHighLevel webhook You can point a GoHighLevel **Workflow → Webhook** action directly at this endpoint — no GHL Marketplace app or action secret required, just your Tuco API key in the `Authorization` header. GHL's Webhook action already includes the full contact payload; Tuco reads GHL's native field names so **the only thing you map in Custom Data is `message`**. **1. Add a Webhook action to your workflow** Method `POST`, URL `https://app.tuco.ai/api/messages`. **2. Add the auth header** `Authorization` = `Bearer tuco_xxxxxxxxxxxxx`. **3. Add Custom Data** Set `message` (required). Optionally add `lineId` (pin a sending line — otherwise Tuco round-robins) and `attachmentUrls` (a single URL or comma-separated list). Tuco auto-maps GHL's native fields onto the canonical request fields. **Custom Data always wins** — set any field there to override what's derived from the contact: | Canonical field | Filled from (Custom Data first, then GHL native) | | - | - | | `message` | `customData.message` | | `fromLineId` | `customData.lineId` | | `attachmentUrls` | `customData.attachmentUrls` (string or CSV → array) | | `recipientPhone` | `customData.recipientPhone` → top-level `phone` | | `recipientEmail` | `customData.recipientEmail` → top-level `email` | | `recipientName` | `customData.recipientName` → `full_name` → `first_name` + `last_name` | | `ghlContactId` | `customData.ghlContactId` → `contact_id` | | `ghlLocationId` | `customData.ghlLocationId` → `location.id` | | `contactOwnerEmail` | `customData.contactOwnerEmail` → `user.email` | > [!NOTE] > > This mapping is **additive and backward compatible** — it only fills a field you did > not already send. Existing integrations that post canonical fields (`recipientPhone`, > `ghlContactId`, …) are completely unaffected. > [!WARNING] > > If `{{contact.phone}}` is empty on the contact, the request fails with > `missing_recipient`. Make sure the contact has a phone or email before the webhook fires. *** ## Response The API always returns **`201`** when the message is successfully created. The `status` field tells you what happens next. > [!TIP] > > **Pre-send checks are never errors.** Line limits, time windows, device gaps, > and contact gaps cause `status: "pending"` or `"scheduled"` — the message is > accepted and will send when conditions are met. ### Success (`201 Created` or `200 OK` when duplicate lead used) ```json theme={null} { "success": true, "status": "sent", "message": { "_id": "69b344bc6dae1d942ece4d0e", "message": "Here's your document.", "messageType": "imessage", "status": "sent", "fromLineId": "69ab427ac1feb77d7f46462e", "recipientPhone": "+919876543210", "recipientEmail": "jane@example.com", "recipientName": "Jane Doe", "leadId": "69b2c41d352a78479d2c623b", "workspaceId": "org_3AZs4H8UsfFxVFONr6H4K75okaG", "createdAt": "2026-03-12T22:57:00.856Z", "updatedAt": "2026-03-12T22:57:02.892Z", "sentAt": "2026-03-12T22:57:02.892Z", "externalMessageId": "5CA93911-F0FE-4D1F-8D8C-1E3495A124F6" }, "leadId": "69b2c41d352a78479d2c623b", "ghlContactId": "aMUQn0u0Z7cw0NQ7tJ5R", "ghlLocationId": "eL7DD22BdZ0rismu7qCA", "hsPortalId": null, "hsContactId": null } ``` When the recipient was matched to an existing lead (duplicate), the API returns **`200`** with `duplicateOnly: true`, `existingLeadIds`, and `leadIds` so your automation can continue without treating it as an error. **success** `boolean` `true` when the message was created. **status** `string` Current status of the message. See the status table below. **message** `object` The full message document. Key fields: **Message fields** **\_id** `string` Unique message ID **message** `string` Body text **messageType** `string` Channel (`imessage`, `sms`, `email`) **status** `string` Lifecycle status **fromLineId** `string` Line used to send **recipientPhone** `string` Recipient phone **recipientEmail** `string` Recipient email **leadId** `string` Linked lead ID **scheduledDate** `string` When the message will send (if scheduled) **sentAt** `string` When actually sent **deliveredAt** `string` When delivery confirmed **createdAt** `string` Creation timestamp ### Accepted but held When a send window, an allowed-day rule or `respectGap` holds the message, the request still succeeds. `status` is `"scheduled"` and `message.scheduledDate` is when it will be released. ```json HTTP 201 — outside the send window, held until it opens theme={null} { "success": true, "status": "scheduled", "leadId": "6ace9f58e350b3be067aef80", "message": { "_id": "6ace9f59e350b3be067aef81", "message": "Morning! Quick question about your quote.", "messageType": "imessage", "direction": "sent", "recipientPhone": "+12025551234", "fromLineId": "6ace9f5622264a6eecd4b333", "leadId": "6ace9f58e350b3be067aef80", "status": "scheduled", "scheduledDate": "2026-10-14T13:00:00.000Z", "settings": { "timezone": "America/New_York", "sendWindowStart": "09:00", "sendWindowEnd": "18:00", "allowedDaysOfWeek": [1, 2, 3, 4, 5] }, "createdAt": "2026-10-13T23:15:05.519Z", "updatedAt": "2026-10-13T23:15:05.771Z" } } ``` `message.settings` echoes the window Tuco stored: the resolved timezone, and `allowedDaysOfWeek` as numbers. ### Status values | Status | Meaning | Is it an error? | | - | - | - | | `"sent"` | Message sent immediately (sync path) | No | | `"pending"` | Created, worker will process. Line limits / time window / device gap may delay it. | **No** — it will send when checks pass | | `"scheduled"` | Held until `message.scheduledDate`: your own `scheduledDate`, a send window or allowed-day rule, a `respectGap` hold, a line limit, or a retry | **No** | | `"cancelled"` | A queued message that was dropped before sending — for example `skipIfReplied` was set and the contact replied while it waited | **No** | | `"fallback"` | Recipient has no iMessage; fallback SMS sent if configured | **No** (business rule) | | `"failed"` | All retries exhausted or availability API error | Yes (technical) | > [!NOTE] > > `"pending"` and `"scheduled"` mean the message is accepted and queued. The worker sends it when: > > * **Time window** is satisfied (inside `sendWindowStart`–`sendWindowEnd`) > * **Allowed day** is satisfied (today is in `allowedDaysOfWeek`) > * **Follow-up gap** has passed (only when `respectGap` is `true`) > * **Line limits** reset (daily total or new conversations limit) > * **Device gap** is met (default 30s between sends from same device) > * **Contact gap** is met (default 45s between first messages to different contacts on same line) > > None of these cause an error response. *** ## Duplicate protection Tuco automatically blocks duplicate sends — no header required. Two POSTs with identical `(workspaceId, recipientPhone, recipientEmail, message)` within **15 minutes** are collapsed: the second one returns `200` with the original message and **does not fire a new send**. ```json HTTP 200 — duplicate caught theme={null} { "success": true, "duplicateOnly": true, "duplicateMessage": "Same message text already sent to this contact 42s ago — returning existing message instead of sending again", "message": { /* the original sibling message doc */ }, "leadId": "..." } ``` Branch on `duplicateOnly === true` and treat it as a no-op success. The `message._id` in the response is the original send, so your CRM workflow can keep moving without re-sending. > [!TIP] > > This works for concurrent firings (the most common cause of accidental > duplicates — an integration retrying within milliseconds) AND for upstream > retries up to 15 minutes apart. The guard is built on an atomic Mongo write, > so concurrent identical POSTs cannot both proceed. > [!NOTE] > > **Failed sends:** if your first send ended in `status: "failed"` and you > immediately retry with the same body within 15 minutes, you'll get the failed > sibling back with `duplicateOnly: true`. To force a fresh send: change the > body or wait 15 minutes. For deeper detail, edge cases, and ops events, see [Atomic Duplicate Guard](/imessage-double-send-guard). `Idempotency-Key` is still supported and runs **before** the dedup guard. Use it when your client controls retries — it gives you a 24-hour window keyed on the exact request rather than on body content. *** ## Skip if the contact already replied Set `skipIfReplied` to avoid following up with a contact who has already responded to you. Tuco checks your workspace's inbound history for this recipient (phone or email) and, if it finds a reply, **does not create or send the message**. This is useful for drip automations in n8n/Make/GHL where you don't want to nudge someone who already wrote back. ### Values | `skipIfReplied` | Behavior | | - | - | | omitted / `false` / `"false"` | Always send (default). | | `true` / `"true"` | Skip if the contact has **ever** replied in your workspace. | | `"1m"` `"1h"` `"1d"` `"2d"` `"5d"` `"7d"` `"14d"` `"1mo"` `"1yr"` | Skip only if they replied **within** that window. | Units: `m` = minute, `h` = hour, `d` = day, `w` = week, `mo` = 30 days, `yr` = 365 days. General form: `` (e.g. `"3d"`, `"36h"`). Note `"1m"` is one **minute** and `"1mo"` is one **month**. > [!NOTE] > > **Scope is your workspace, not a single line.** A reply to *any* of your lines counts — > which line you send from doesn't matter. The check is strictly scoped to your workspace > and never sees another workspace's replies. ### Request ```bash Skip the follow-up if they replied in the last 7 days theme={null} curl -X POST "https://app.tuco.ai/api/messages" \ -H "Authorization: Bearer tuco_xxxxxxxxxxxxx" \ -H "Content-Type: application/json" \ -d '{ "message": "Just following up — still interested?", "recipientPhone": "+12025551234", "skipIfReplied": "7d" }' ``` ### Response when the send is skipped (`200 OK`) No message is created. `success` is `true` (the request was handled — do **not** retry) and `skippedOnly` distinguishes it from a real send. ```json HTTP 200 — skipped because the contact already replied theme={null} { "success": true, "skippedOnly": true, "skipReason": "recipient_replied", "skipMessage": "Skipped: this contact already replied in your workspace within the last 7d. The skipIfReplied gate prevented this send.", "repliedAt": "2026-06-27T18:40:11.020Z", "message": null, "leadId": "667f1f77bcf86cd799439012" } ``` Branch on `skippedOnly === true` and treat it as a successful no-op. When the contact has **not** replied (or replied outside the window), the request proceeds exactly as a normal send and returns the usual `201` response. > [!WARNING] > > An unrecognized `skipIfReplied` value returns **400** with > `code: "INVALID_SKIP_IF_REPLIED"`. Use `true`, `false`, or one of the documented > window strings. Every decision is logged internally (`message.api.skipped_replied`, `message.api.skip_if_replied_passed`, `message.api.skip_if_replied_invalid`) under your `correlationId`, so you can audit exactly why a send was or wasn't suppressed. ### A queued message is checked again before it sends `skipIfReplied` is evaluated when you call the API **and again right before the message is sent**. If a message is waiting — for a `scheduledDate`, a send window, a line limit, a line that is down, or a `respectGap` hold — and the contact replies in the meantime, the message is **cancelled** instead of sent (its status becomes `cancelled`). With a window value such as `"1h"`, the second check looks back from the moment of sending, not from when you made the request. *** ## Keep the wait between follow-ups Automations usually space follow-ups out: message 1, wait, message 2. If message 1 goes out late — held by a send window, a line limit, pacing, or a line that was briefly down — message 2 can land right behind it and the wait you designed disappears. Set `respectGap: true` on the follow-up to keep that wait. ### How the hold is calculated Tuco looks at the most recent message already sent to the same contact in your workspace and holds the new one until: ``` previous message's actual send time + (this request's time − previous request's time) ``` So the gap between your two **API calls** is preserved, measured from when the previous message **really went out**. It does not use `scheduledDate`. | | Request made | Actually sent | | - | - | - | | Message 1 | 10:00:00 | 10:07:00 (held 7 minutes) | | Message 2, `respectGap: true` | 10:05:00 (5 minutes after message 1) | held until 10:12:00, then sent | | Message 2, no `respectGap` | 10:05:00 | sent as soon as it is free — right behind message 1 | ### Request ```bash Follow-up that keeps its spacing theme={null} curl -X POST "https://app.tuco.ai/api/messages" \ -H "Authorization: Bearer tuco_xxxxxxxxxxxxx" \ -H "Content-Type: application/json" \ -d '{ "message": "Just checking you saw my last note", "recipientPhone": "+12025551234", "respectGap": true }' ``` The response is the usual `201`. When the message is being held, `status` is `"scheduled"` and `scheduledDate` is the time it is held until: ```json HTTP 201 — held to keep the gap theme={null} { "success": true, "status": "scheduled", "leadId": "6ace83280fadae5820a37ae4", "message": { "_id": "6ace83bd0fadae5820a37b01", "message": "Just checking you saw my last note", "messageType": "imessage", "direction": "sent", "recipientPhone": "+12025551234", "fromLineId": "6ace832115ae149cfdf83db7", "leadId": "6ace83280fadae5820a37ae4", "status": "scheduled", "respectGap": true, "scheduledDate": "2026-10-13T19:18:29.579Z", "createdAt": "2026-10-13T19:17:17.937Z", "updatedAt": "2026-10-13T19:17:18.274Z" } } ``` ### Without `respectGap`: a 1-minute minimum ![A three-step sequence whose first step goes out late: by default the steps go out at least a minute apart; with respectGap the full gaps are kept; a reply cancels the remaining steps with skipIfReplied](https://mintcdn.com/tucoai/SoLkNcvAIeibvkGp/images/sequence-late-step.png?fit=max\&auto=format\&n=SoLkNcvAIeibvkGp\&q=85\&s=61ac41c85104d24bb7e2528e4a906e85) Even when you don't set `respectGap`, Tuco never lets a late message drag the next one out right behind it. If two messages to the same contact were planned **at least 1 minute apart** and the first one went out late, the second goes out **at least 1 minute after the first one actually sent**. "Planned" means the `scheduledDate` you sent, or the time of your API call. | | Planned | Actually sent | | - | - | - | | Message 1 | 10:00 | 10:40 (held by a line limit) | | Message 2, planned +15 min, no `respectGap` | 10:15 | 10:41 (1 minute after message 1) | | Message 2, planned +30 s (bubble), no `respectGap` | 10:00:30 | 10:40, right behind message 1 | | Message 2, `respectGap: true`, API call made at 10:15 | 10:15 | 10:55 (the full 15 minutes between the two calls) | Messages planned less than a minute apart (a reply split into several bubbles) still go together. A message you type in the inbox to send now, or any message after the contact has replied, is never held. With `skipIfReplied`, a reply during the wait cancels the next message. Set `respectGap: true` to keep the full planned gap instead. ### What to expect * **Works without a send window.** `respectGap` needs no `sendWindowStart`, `sendWindowEnd` or `timezone`. * **It is per contact, across all your lines.** The previous message can have gone out from a different line. Messages to other contacts are never affected. * **The first message to a contact is never held** — there is nothing to space it from. * **"Previous message" means the latest one sent to that contact**, whatever sent it. A manual reply from the inbox in between becomes the new reference point. * **The gap is a minimum.** Held messages are released about once a minute, so the real spacing is the gap plus up to a minute. * **A send window still wins.** If the hold ends outside `sendWindowStart`–`sendWindowEnd` (or on a day not in `allowedDaysOfWeek`), the message waits for the window to open. * **If the earlier message went out on time, nothing changes** — the follow-up sends normally. * **Combine it with `skipIfReplied`** to drop the follow-up if the contact answers while it is being held. * Only `true` or `"true"` turn it on. Any other value is treated as off. > [!WARNING] > > `respectGap` spaces a follow-up from a message that has **already been sent**. If the > earlier message is still waiting when the follow-up arrives, there is nothing to measure > from yet, so `respectGap` does not hold the follow-up. With several lines, if the > earlier message is pinned to a line that is down (`fromLineId`) > and the follow-up is not pinned, the follow-up can go out first on a healthy line — > pin both to the same line, or leave both unpinned, to avoid that. *** ## Send window and allowed days | You send | What happens | | - | - | | No window fields | Sends immediately (subject to line limits and pacing). | | `sendWindowStart` + `sendWindowEnd`, inside the window | Sends immediately. | | `sendWindowStart` + `sendWindowEnd`, outside the window | `201`, `status: "scheduled"`, held until the window next opens. | | Only one of the two | The window is ignored. | | No `timezone` | Workspace timezone, then `America/New_York`. | | An unknown `timezone`, or an abbreviation like `"EST"` | `400 INVALID_TIMEZONE`. | | `allowedDaysOfWeek` without both window times | The day list is ignored. | | A time that isn't `HH:mm` (e.g. `"9am"`, `"25:00"`) | `400`. | | Start not earlier than end (`"22:00"`–`"06:00"`, `"09:00"`–`"09:00"`) | `400 INVALID_SEND_WINDOW`. | | `allowedDaysOfWeek` that isn't whole numbers `0`–`6` (e.g. `[7]`, `[1.5]`, `"monday"`) | `400 INVALID_ALLOWED_DAYS`. | ### Request ```bash Weekdays, 9am–6pm New York theme={null} curl -X POST "https://app.tuco.ai/api/messages" \ -H "Authorization: Bearer tuco_xxxxxxxxxxxxx" \ -H "Content-Type: application/json" \ -d '{ "message": "Morning! Quick question about your quote.", "recipientPhone": "+12025551234", "sendWindowStart": "09:00", "sendWindowEnd": "18:00", "timezone": "America/New_York", "allowedDaysOfWeek": [1, 2, 3, 4, 5] }' ``` Inside the window on an allowed day the response is the normal `201` with `status: "sent"`. Outside it you get `201` with `status: "scheduled"` — see [Accepted but held](#accepted-but-held). ### Rejected values (`400`) ```json Overnight window theme={null} { "error": "sendWindowStart must be earlier than sendWindowEnd. Overnight windows (e.g. \"22:00\"–\"06:00\") are not supported; use \"00:00\"–\"23:59\" to send at any hour.", "code": "INVALID_SEND_WINDOW" } ``` ```json Timezone abbreviation theme={null} { "error": "\"EST\" is an abbreviation with a fixed offset that ignores daylight saving. Use an IANA timezone name such as \"America/New_York\" or \"Europe/London\", or omit timezone to use your workspace timezone.", "code": "INVALID_TIMEZONE" } ``` ```json Unknown timezone theme={null} { "error": "\"Mars/Phobos\" is not a recognized timezone. Use an IANA timezone name such as \"America/New_York\" or \"Europe/London\", or omit timezone to use your workspace timezone.", "code": "INVALID_TIMEZONE" } ``` ```json Bad day list theme={null} { "error": "allowedDaysOfWeek must be an array of whole numbers from 0 (Sunday) to 6 (Saturday), e.g. [1,2,3,4,5].", "code": "INVALID_ALLOWED_DAYS" } ``` ```json Bad time format theme={null} { "error": "Invalid time format. sendWindowStart and sendWindowEnd must be in HH:mm format (e.g., 09:00, 17:00)" } ``` Day numbers sent as strings (`["1","2","3"]`) are accepted and stored as numbers. ### The window is checked again every time the message is about to send The window you put on a message is checked when you call the API **and again each time Tuco is about to send it**. So if something delays the message — a failed attempt that is retried a few minutes later, a line that was briefly down, a daily or hourly limit — and the window has closed in the meantime, the message waits for the window to open again instead of going out late. `allowedDaysOfWeek` is applied the same way: on a day that isn't allowed, the message waits for `sendWindowStart` on the next allowed day. This applies to every message sent through the API that carries its own `sendWindowStart` and `sendWindowEnd`. These checks only run when a send window is set. Without `sendWindowStart` and `sendWindowEnd`, `timezone` and `allowedDaysOfWeek` are ignored. *** ## Errors Errors are returned only for **validation failures** — never for pre-send checks. | Status | When | Example | | - | - | - | | `400` | Message and attachments both empty | `{ "error": "Message and attachmentUrls cannot both be empty" }` | | `400` | Invalid `messageType` | `{ "error": "Invalid messageType. Must be email, sms, or imessage" }` | | `400` | No active lines + no `fromLineId` | `{ "error": "No active lines in workspace..." }` | | `400` | No recipient anywhere | `{ "error": "Either recipientEmail or recipientPhone is required..." }` | | `400` | Unrecognized `skipIfReplied` value | `{ "error": "...", "code": "INVALID_SKIP_IF_REPLIED" }` | | `400` | `{firstName}`/`{lastName}` has no value and no fallback, an unfilled non-Tuco token (`{{contact_name}}`), or a name expanded to nothing | `{ "error": "Malformed message: name template variable is empty...", "code": "MALFORMED_NAME_TEMPLATE" }` | | `400` | Any other template variable has no value and no fallback | `{ "error": "Template variable(s) have no value...", "code": "TEMPLATE_VARIABLE_UNRESOLVED", "unresolvedVariables": ["line_email"] }` | | `400` | `voiceNote: true` with no attachment | `{ "error": "voiceNote: true needs an audio attachment...", "code": "VOICE_NOTE_NO_ATTACHMENT" }` | | `400` | `voiceNote: true` with a non-audio attachment | `{ "error": "voiceNote: true needs a direct link to an audio file...", "code": "VOICE_NOTE_NOT_AUDIO" }` | | `400` | `fromLineId` is not a line in your workspace | `{ "error": "The specified line does not belong to this workspace.", "code": "LINE_NOT_FOUND" }` | | `400` | More than 2 attachments | `{ "error": "Maximum 2 attachments per message" }` | | `400` | Attachment URL belongs to another workspace | `{ "error": "Attachment URL does not belong to this organization" }` | | `400` | Every attachment is unreachable and there is no text | `{ "error": "No attachment is sendable and the message text is empty...", "code": "ATTACHMENT_UNSENDABLE_NO_TEXT" }` | | `400` | `recipientPhone` can't be dialled (bad NANP area/exchange code) | `{ "error": "That number can't receive messages (exchange code 019 cannot start with 0 or 1). Message not sent." }` | | `400` | Bad `scheduledDate` or `sendWindowStart`/`sendWindowEnd` format | `{ "error": "Invalid scheduledDate format" }` | | `400` | Send window start not earlier than end | `{ "error": "...", "code": "INVALID_SEND_WINDOW" }` | | `400` | Timezone abbreviation or unknown timezone (with a send window) | `{ "error": "...", "code": "INVALID_TIMEZONE" }` | | `400` | `allowedDaysOfWeek` not whole numbers 0–6 (with a send window) | `{ "error": "...", "code": "INVALID_ALLOWED_DAYS" }` | | `401` | Invalid or missing API key | `{ "error": "Unauthorized" }` | | `402` | Subscription past due (workspace read-only) | `{ "error": "READ_ONLY", "code": "READ_ONLY", "reason": "past_due" }` | | `404` | `leadId` provided but not found | `{ "error": "Lead not found or access denied" }` | *** ## What happens after the API call **1. Message created** Tuco inserts a record in the `messages` collection with status `pending` (or `scheduled` if `scheduledDate` is provided). **2. Pre-send checks (worker)** The worker checks line limits, time window, device gap, and contact gap. If any fail, the message stays **queued** and is retried later — not failed. **3. Availability check** If the workspace has a line with Private API, Tuco checks whether the recipient supports iMessage. If not → status becomes `fallback` and fallback SMS fires (when configured). > [!NOTE] > > `forceFallback: true` **skips this step entirely** — the message goes > straight to the configured fallback channel and never runs an availability > check (so it doesn't consume the availability-check budget or line cap). **4. Send** For individual messages: up to **5 send attempts** with delivery verification between each (polling for up to 90 seconds). **5. Outcome** `sent` → appears in Unibox + webhook fires. `failed` → error recorded + optional fallback SMS. `delivered` → confirmed later via device callbacks. *** ## Lead resolution When you send without a `leadId`, Tuco resolves the recipient automatically: > [accordion] Lead found by phone/email > > If an existing lead in your workspace matches the `recipientPhone` or > `recipientEmail`, the message is linked to that lead. Any `altPhone`/`altEmail` > fields you pass will **update** the lead (merge, not overwrite). > [accordion] New lead created (Quick Sends) > > If no matching lead exists, Tuco creates one under a list called **"Quick Sends"** > (created automatically if it doesn't exist). Alt contact fields are stored on > the new lead. > [accordion] leadId provided > > The lead must exist in your workspace. The message is linked to it. > `recipientPhone`/`recipientEmail` from the body override the lead's stored > contact for this specific send. *** ## Alt contact fields When you pass `altPhone1`–`altPhone3` or `altEmail1`–`altEmail3`, they are stored on the **lead** (not the message). The worker uses them as fallback addresses when the primary address fails the iMessage availability check. **Priority order for `messageType: "imessage"`:** ``` phone → altPhone1 → altPhone2 → altPhone3 → email → altEmail1 → altEmail2 → altEmail3 ``` > [!WARNING] > > Alt fields are **merged** onto the lead. If a lead already has `altPhone1` set > and you send a new message without `altPhone1`, the existing value is preserved. > Only explicitly provided fields are overwritten. *** ## Fallback SMS on failure By default, when a message fails (technical error), no SMS fallback is sent. To enable: 1. Configure Twilio on your workspace (`GET /api/workspace/fallback-config`). 2. Set `sendFallbackSmsOnFailed: true` in the request body (per-message) or on the workspace (applies to all messages). > [!NOTE] > > Setting `sendFallbackSmsOnFailed: true` without a configured fallback is **not an error**. > The request returns `201` and the iMessage send goes ahead as normal — there is simply no > SMS to fall back to if it fails. Read > [`GET /api/workspace/fallback-config`](/api-reference/endpoint/fallback-config) to confirm > a fallback is set up before you rely on it. | Scenario | Fallback SMS fires? | | - | - | | Status = `fallback` (no iMessage), Twilio configured | **Yes** — always | | Status = `failed`, `sendFallbackSmsOnFailed: true`, Twilio configured | **Yes** | | Status = `failed`, `sendFallbackSmsOnFailed: false` (default) | **No** | | Status = `failed`, flag is `true` but no fallback configured | **No** — the send is accepted, there is just nothing to fall back to | > [!NOTE] > > Fallback SMS requires `recipientPhone` on the message. Email-only messages > will not trigger fallback SMS. # Send Reaction Source: https://docs.tuco.ai/api-reference/endpoint/send-reaction POST /api/messages/react Send an iMessage tapback reaction to an existing message in your workspace. REST endpoint in the Tuco AI iMessage API — bearer-token auth, JSON. > [!NOTE] > > Use this endpoint to react to an existing message with a native iMessage tapback. > The target message must already exist in Tuco and belong to your workspace. ## What This Endpoint Does This endpoint adds a native iMessage reaction to an existing message in a conversation. It is useful when you want your integration to behave more like a human operator in Unibox, for example: * acknowledging a message with a quick tapback * reacting before sending a longer reply * mirroring a lightweight action a user took in your own system ## Authentication Pass your workspace API key as a Bearer token, or use a Clerk session token. ```bash theme={null} Authorization: Bearer tuco_xxxxxxxxxxxxx ``` *** ## Request body **messageId** `string` The Tuco message ID to react to. Required. **reaction** `string` Required reaction type. Supported values: * `"love"` * `"like"` * `"dislike"` * `"laugh"` * `"emphasize"` * `"question"` *** ## Example ```bash theme={null} curl -X POST "https://app.tuco.ai/api/messages/react" \ -H "Authorization: Bearer tuco_xxxxxxxxxxxxx" \ -H "Content-Type: application/json" \ -d '{ "messageId": "6a07878bafb1789f8fcb68e6", "reaction": "love" }' ``` *** ## Response ### Success (`200 OK`) ```json theme={null} { "ok": true, "reaction": "love" } ``` ### Error responses | Status | When | Body | | - | - | - | | `400` | `messageId` or `reaction` is missing | `{ "error": "messageId and reaction required" }` | | `400` | `reaction` is not supported | `{ "error": "Invalid reaction type" }` | | `400` | `messageId` is not a valid ObjectId | `{ "error": "Invalid messageId" }` | | `400` | The target message cannot be resolved to a valid iMessage chat target | `{ "error": "Cannot determine contact phone for reaction" }` | | `400` | The target message has no upstream message ID | `{ "error": "Message has no upstream ID — cannot react" }` | | `400` | The target line is missing required relay credentials | `{ "error": "Line not found or missing credentials" }` | | `401` | Missing or invalid API key / session | `{ "error": "Unauthorized" }` | | `404` | Message not found in your workspace | `{ "error": "Message not found" }` | | `502` | The upstream provider returned an error | `{ "error": "Upstream provider error: ..." }` | *** ## Notes * Reactions are workspace-scoped: you can only react to messages inside your own workspace. * Sending the same reaction again toggles it off. * Tuco keeps only one outbound self-reaction per message at a time, matching native iMessage behavior. * If you also want to receive inbound reactions from leads, see [Message Webhooks](/api-reference/message-webhooks#message-reaction). # Send Test Webhook Source: https://docs.tuco.ai/api-reference/endpoint/send-test-webhook POST /api/webhooks/{id}/test Send a realistic, signed test event to your Tuco webhook: heartbeat, message sent (attachment, voice note, P2P SMS), reply, fallback and more. Sends a test event to your webhook endpoint, signed with your webhook secret exactly like a live delivery. Each test payload is built by the same code that builds live webhooks, so a test that passes means your parser handles the real event. Tests are marked with the `X-Tuco-Test: true` header and `"testMode": true` in the body. They appear in the [delivery log](/api-reference/endpoint/list-webhook-deliveries) and never count as failures on your webhook. ## Authentication ```bash theme={null} Authorization: Bearer tuco_xxxxxxxxxxxxx ``` ## Path parameters **id** `string` *required* Webhook ID. ## Body Send no body to test every event the webhook subscribes to (one request per event). **event** `string` Send only this event. Any event below, including `heartbeat`, even if the webhook is not subscribed to it. **variant** `string` Payload variant for the event. Defaults to the first variant listed for that event. | `event` | `variant` (first is the default) | | - | - | | `heartbeat` | `default` | | `message.sent` | `text`, `attachment`, `pdf`, `link`, `voice_note`, `p2p_sms` | | `message.reply` | `text`, `attachment`, `pdf`, `voice_note` | | `message.failed` | `strike_2`, `expired` | | `message.fallback` | `default` | | `message.opened` | `default` | | `message.reaction` | `default` | | `message.ai_draft` | `default` | | `message.ai_draft_approved` | `default` | | `message.ai_draft_rejected` | `default` | | `conversation.handover` | `default` | | `call.recording.ready` | `default` | | `dnc.added` | `opt_out` (replied STOP), `manual` (added via API / dashboard) | | `group.message.received` | `text`, `attachment` | | `group.message.sent` | `text`, `attachment`, `voice_note` | | `group.message.failed` | `default` | | `group.message.reaction` | `default` | ## Response **ok** `boolean` `true` when every test got a `2xx`. **status** `number` Your endpoint's HTTP status for the first failing test, or the last test. **statusText** `string` Status text, or `Timeout (10s)` / the network error. **latency** `number` Milliseconds for that request. **body** `string` First 500 characters of your endpoint's last response. **results** `array` One entry per test: `event`, `variant`, `ok`, `status`, `statusText`, `latency`. | Status | When | | - | - | | `200` | Tests were sent (check `ok` for your endpoint's result) | | `400` | Unknown `event` or `variant`, invalid JSON, or the webhook is inactive | | `401` | Missing or invalid API key | | `404` | Webhook not found in your workspace | ## Examples ```bash theme={null} curl -X POST "https://app.tuco.ai/api/webhooks/680a1b2c3d4e5f6789012345/test" \ -H "Authorization: Bearer tuco_xxxxxxxxxxxxx" \ -H "Content-Type: application/json" \ -d '{"event": "message.sent", "variant": "p2p_sms"}' ``` ```json heartbeat theme={null} { "event": "heartbeat", "testMode": true, "timestamp": "2026-10-15T21:26:17.747Z", "workspaceId": "org_xxx", "data": {} } ``` ```json message.sent · p2p_sms theme={null} { "event": "message.sent", "timestamp": "2026-10-15T21:26:17.748Z", "workspaceId": "org_xxx", "leadId": "7e57ab1e0000000000000001", "lead": { "_id": "7e57ab1e0000000000000001", "firstName": "Test", "lastName": "Contact", "email": "test.contact@example.com", "phone": "+15551234567", "companyName": "Test Co", "listId": "7e57ab1e0000000000000004", "workspaceId": "org_xxx", "source": "api", "createdAt": "2026-01-01T00:00:00.000Z", "updatedAt": "2026-01-01T00:00:00.000Z" }, "messageId": "7e57ab1e0000000000000002", "message": { "_id": "7e57ab1e0000000000000002", "message": "This is a test webhook from Tuco. If you see this, your endpoint is working correctly.", "messageType": "imessage", "direction": "sent", "recipientPhone": "+15551234567", "recipientName": "Test Contact", "fromLineId": "7e57ab1e0000000000000003", "fromLinePhone": "+15557654321", "fromLineEmail": "line@example.com", "leadId": "7e57ab1e0000000000000001", "source": "api", "workspaceId": "org_xxx", "createdByUserId": "user_test", "status": "sent", "externalMessageId": "TEST-0000-0000-0000-000000000001", "createdAt": "2026-10-15T21:26:17.748Z", "updatedAt": "2026-10-15T21:26:17.748Z", "sentAt": "2026-10-15T21:26:17.748Z", "smsForwarded": true, "smsForwardedAt": "2026-10-15T21:26:17.748Z", "smsForwardedMethod": "apple-script" }, "contactOwnerEmail": null, "ghlContactId": null, "ghlLocationId": null, "hsPortalId": null, "hsContactId": null, "channel": "p2p_sms", "data": {}, "testMode": true } ``` ```json message.reply · attachment theme={null} { "event": "message.reply", "timestamp": "2026-10-15T21:26:17.749Z", "workspaceId": "org_xxx", "leadId": "7e57ab1e0000000000000001", "lead": { "_id": "7e57ab1e0000000000000001", "firstName": "Test", "lastName": "Contact", "email": "test.contact@example.com", "phone": "+15551234567", "companyName": "Test Co", "listId": "7e57ab1e0000000000000004", "workspaceId": "org_xxx", "source": "api", "createdAt": "2026-01-01T00:00:00.000Z", "updatedAt": "2026-01-01T00:00:00.000Z" }, "messageId": "7e57ab1e0000000000000006", "message": "", "firstName": "Test", "lastName": "Contact", "phone": "+15551234567", "listId": "7e57ab1e0000000000000004", "fromLineId": "7e57ab1e0000000000000003", "recipientName": "Test Contact", "contactOwnerEmail": null, "repliedAtUtc": "2026-10-15T21:26:17.748Z", "parentMessages": [], "ghlContactId": null, "ghlLocationId": null, "hsPortalId": null, "hsContactId": null, "optedOut": false, "attachmentUrls": [ "https://example.private.blob.vercel-storage.com/tuco-test/photo.jpeg" ], "attachmentDownloadUrls": [ "https://app.tuco.ai/api/attachments/crm-media/photo.jpeg?u=aHR0cHM6Ly9leGFtcGxlLnByaXZhdGUuYmxvYi52ZXJjZWwtc3RvcmFnZS5jb20vdHVjby10ZXN0L3Bob3RvLmpwZWc&exp=1794691577749&sig=T4YoMYGXdllKOG1bS-yVmbdD9njn-gfW98c4Gi3SA2M" ], "attachmentNames": [ "photo.jpeg" ], "data": { "reply": { "leadId": "7e57ab1e0000000000000001", "messageId": "7e57ab1e0000000000000006", "respondedAtUtc": "2026-10-15T21:26:17.748Z", "recipientPhone": "+15551234567", "name": "Test Contact", "recentReplies": [], "parentMessages": [], "attachmentUrls": [ "https://example.private.blob.vercel-storage.com/tuco-test/photo.jpeg" ], "attachmentDownloadUrls": [ "https://app.tuco.ai/api/attachments/crm-media/photo.jpeg?u=aHR0cHM6Ly9leGFtcGxlLnByaXZhdGUuYmxvYi52ZXJjZWwtc3RvcmFnZS5jb20vdHVjby10ZXN0L3Bob3RvLmpwZWc&exp=1794691577749&sig=T4YoMYGXdllKOG1bS-yVmbdD9njn-gfW98c4Gi3SA2M" ], "attachmentNames": [ "photo.jpeg" ] }, "repliedAtUtc": "2026-10-15T21:26:17.748Z", "parentMessages": [] }, "testMode": true } ``` # Send Typing Indicator Source: https://docs.tuco.ai/api-reference/endpoint/send-typing-indicator POST /api/messages/typing Start a short iMessage typing signal before sending a message. REST endpoint in the Tuco AI iMessage API — bearer-token auth, JSON request/response, full. > [!NOTE] > > This endpoint is best-effort visual polish. It should not block your send flow. Native clients can clear typing on their own timing. ## When To Use This Endpoint Use typing when you want your integration to feel more natural right before a real reply. Common usage: 1. your system decides it is about to respond 2. you call `POST /api/messages/typing` 3. you wait a short moment 4. you send the actual message Typing should be treated as visual sugar, not a required part of delivery. ## Authentication Pass your workspace API key as a Bearer token, or use a Clerk session token. ```bash theme={null} Authorization: Bearer tuco_xxxxxxxxxxxxx ``` *** ## Request body **messageId** `string` Required. A Tuco message id in your workspace. Tuco uses it to resolve the correct line and chat target. *** ## Start typing ```bash theme={null} curl -X POST "https://app.tuco.ai/api/messages/typing" \ -H "Authorization: Bearer tuco_xxxxxxxxxxxxx" \ -H "Content-Type: application/json" \ -d '{ "messageId": "6a07878bafb1789f8fcb68e6" }' ``` ### Success (`200 OK`) ```json theme={null} { "ok": true, "typing": true, "note": "Typing started. the messaging backend clears typing automatically; use this as a short pre-send signal." } ``` *** ## Stop typing Use the same endpoint with `DELETE`. ```bash theme={null} curl -X DELETE "https://app.tuco.ai/api/messages/typing" \ -H "Authorization: Bearer tuco_xxxxxxxxxxxxx" \ -H "Content-Type: application/json" \ -d '{ "messageId": "6a07878bafb1789f8fcb68e6" }' ``` ### Success (`200 OK`) ```json theme={null} { "ok": true, "typing": false, "note": "Stop-typing sent best-effort. Native clients may clear typing on their own timing." } ``` *** ## Error responses | Status | When | Body | | - | - | - | | `400` | Message cannot be resolved to a valid chat target | `{ "error": "..." }` | | `401` | Missing or invalid API key / session | `{ "error": "Unauthorized" }` | | `502` | The upstream provider returned an error | `{ "error": "Upstream provider error: ..." }` | *** ## Notes * Use typing shortly before a real send. * Treat stop-typing as best effort only. * Do not depend on typing indicators for delivery correctness. * The most reliable way to end typing is still sending the real message. # Send with Attachments Source: https://docs.tuco.ai/api-reference/endpoint/send-with-attachments POST /api/messages Send images, videos, voice notes, and files via iMessage — with or without text. REST endpoint in the Tuco AI iMessage API — bearer-token auth, JSON. > [!WARNING] > > **The Try it panel runs against production** (`https://app.tuco.ai`) with the key you paste > into it. There is no sandbox — a request from this page sends a real message from one of your lines. Send attachments alongside or instead of text messages. Tuco handles downloading, caching, and delivering files through your device relay. ## Request body Use the same `POST /api/messages` endpoint. Add `attachmentUrls` to your request: **attachmentUrls** `string[]` *required* Array of public URLs to attach. **Max 2 attachments per message, max 25 MB each.** **attachmentNames** `string[]` Optional display names for each attachment (same order as `attachmentUrls`). When omitted, the filename from the URL is used. **message** `string` Optional text to send with the attachments. When omitted, only the attachment is sent (no "Attachment" placeholder text). **recipientPhone** `string` **The phone number to text, in E.164 format** (e.g. `"+12025551234"`). This is how you address almost every send — you do not need a Tuco `leadId`. Tuco finds the matching lead in your workspace, or creates one under the **Quick Sends** list automatically. Required unless you pass `leadId` or `recipientEmail`. **leadId** `string` Send to an existing lead using their stored contact details. Required unless you pass `recipientPhone` or `recipientEmail`. **recipientEmail** `string` > [!WARNING] > > **Use `recipientPhone` unless you specifically need this.** An email address only reaches someone > over iMessage if that exact address is registered to their Apple account — rare, and not something > you can assume. Addressing by phone number is what works. Required unless you pass `recipientPhone` or `leadId`. **voiceNote** `boolean` (default: false) Send a single audio attachment as a **native iMessage voice note** (the waveform bubble) instead of a generic audio file. Accepts `true` or the string `"true"`. Tuco transcodes whatever audio you supply — MP3, M4A, WAV, AAC, OGG, OPUS, FLAC, AIFF, AMR, CAF — into the exact format iMessage needs, so you do **not** have to convert anything yourself. The request is **rejected with a 400** if `voiceNote` is set and the attachment is not audio (a video, an image, or a web-page link), rather than sending something that cannot become a waveform. See [Voice note requirements](#voice-note-requirements). > [!NOTE] > > All other [`POST /api/messages`](/api-reference/endpoint/send-message) body fields > apply here too — including [`forceFallback`](/api-reference/endpoint/send-message) > (skip the iMessage availability check and route straight to your configured > fallback). One caveat: the SMS/fallback channel is text-only, so a `forceFallback` > send delivers the `message` text but **not** the attachments — those go over > iMessage only. *** ## Supported formats | Category | Formats | Notes | | - | - | - | | Images | PNG, JPG, JPEG, GIF, WebP, HEIC | Renders inline in iMessage | | Video | MP4, MOV | Up to 25 MB. Renders as playable video | | Audio / Voice notes | MP3, M4A, WAV, AAC, OGG, WebM, FLAC, CAF | Sent as a generic audio file by default. Add `"voiceNote": true` to deliver it as a native iMessage voice note (the waveform bubble) — Tuco transcodes it for you | | Documents | PDF | Renders as attachment preview | *** ## Voice notes An audio attachment sends as a **generic audio file** by default. To get the native iMessage voice note — the waveform bubble with a play button — add `voiceNote: true`: ```json theme={null} { "recipientPhone": "+12025551234", "attachmentUrls": ["https://example.com/voice-note.mp3"], "voiceNote": true } ``` Tuco transcodes your audio server-side into the one format iMessage renders natively (Opus mono in a CAF container) and validates the result before sending. **You do not need to convert the file yourself** — MP3, M4A (iPhone Voice Memos), WAV, AAC, OGG, OPUS, FLAC, AIFF, AMR and CAF all work. ### Voice note requirements All five have to be true. These are conditions on the audio you link to, not request fields. > [card] A direct link to an audio FILE > > The URL has to return the audio itself. A **YouTube, Google Drive or Dropbox share page > is a web page, not a file** — those are rejected. So is any link that needs a login. > [card] Publicly reachable, no authentication > > Our sending device fetches the URL directly. If it needs a cookie, a session or a > signed-in browser, the fetch fails and nothing is sent. > [card] Under 5 minutes > > Recordings longer than 300 seconds are rejected. > [card] Under 25 MB > > Same ceiling as every other attachment sent by URL. Files you push through > [`POST /api/attachments/upload`](/api-reference/upload-attachment) have a tighter **5 MB** cap. > [card] Not the first message to a contact > > The first-ever message to a new contact must be plain text — no attachment or voice > note. Send a text first, then the voice note as a follow-up. > [!TIP] > > **The easy way to get a valid URL:** upload the recording in the app under > **Leads → Uploads** (`/leads?tab=uploads`) and use the link it gives you back. That link > is already public, direct, and correctly typed — which is what most failed voice notes > turn out to be missing. > [!NOTE] > > **What happens if the audio is wrong.** Tuco converts your file and then *verifies its own > output* before sending. If the result would not play — the wrong codec, a stereo track, a > corrupt file — the send is **stopped** and the message is marked failed with the reason. > We do not deliver a silent `0:00` bubble. You will see one of these on the message: > > | What you see | What to do | > | - | - | > | That link isn't an audio file | Use a direct file URL, not a web page | > | Voice note unreachable | The link isn't public — re-upload it | > | Voice note too long | Trim it under 5 minutes | > | Voice note couldn't be sent | Re-record, or upload a standard MP3/M4A/WAV | > | This line can't send voice notes | Contact support | > [!WARNING] > > **Do not rename an MP3 to `.caf`.** Tuco treats any `.caf` as a finished voice note > and sends it as-is, so a renamed MP3 (or a `.caf` from a consumer web converter, > which is usually PCM rather than Opus) is **rejected and not sent** — it would > otherwise arrive as a dead `0:00` bubble. Send the original `.mp3` with > `voiceNote: true` and let Tuco encode it. > [!NOTE] > > Passing `voiceNote: true` alongside a real `.caf` is always safe: a valid voice note > passes straight through untouched, and an invalid one gets re-encoded instead of > rejected. If you are sending `.caf` files you did not produce with > `afconvert -f caff -d opus@24000 -c 1`, include the flag. ### When a voice note will not send Voice notes fail **permanently** (no retry) in these cases, and the reason is shown on the message in your Unibox: | Reason | What happened | | - | - | | First message to a new contact | The first-ever message to a contact must be plain text — no attachment or voice note. Send text first, then the voice note as a follow-up. | | Attachment is a web page, not audio | `attachmentUrls` pointed at a YouTube/Calendly-style page instead of a direct audio file URL. | | Audio longer than 5 minutes | Voice notes are capped at 300 seconds. | | Attachment is not audio | `voiceNote: true` with an image or PDF. | | Line cannot send voice notes | The line's device relay does not currently support native voice notes. Contact support. | *** ## Examples ```bash Image + text theme={null} curl -X POST "https://app.tuco.ai/api/messages" \ -H "Authorization: Bearer tuco_xxxxxxxxxxxxx" \ -H "Content-Type: application/json" \ -d '{ "message": "Check this out!", "recipientPhone": "+12025551234", "attachmentUrls": ["https://example.com/photo.jpg"] }' ``` ```bash Voice note (any audio) theme={null} curl -X POST "https://app.tuco.ai/api/messages" \ -H "Authorization: Bearer tuco_xxxxxxxxxxxxx" \ -H "Content-Type: application/json" \ -d '{ "recipientPhone": "+12025551234", "attachmentUrls": ["https://app.tuco.ai/api/attachments/crm-media/-note.mp3"], "voiceNote": true }' ``` ```bash Video only (no text) theme={null} curl -X POST "https://app.tuco.ai/api/messages" \ -H "Authorization: Bearer tuco_xxxxxxxxxxxxx" \ -H "Content-Type: application/json" \ -d '{ "recipientPhone": "+12025551234", "attachmentUrls": ["https://example.com/intro-video.mp4"] }' ``` ```bash Video + text in one message theme={null} curl -X POST "https://app.tuco.ai/api/messages" \ -H "Authorization: Bearer tuco_xxxxxxxxxxxxx" \ -H "Content-Type: application/json" \ -d '{ "message": "I made this for you. Whenever you are ready: example.com/schedule", "recipientPhone": "+12025551234", "attachmentUrls": ["https://example.com/personalized-video.mp4"] }' ``` ```bash Send to an existing lead theme={null} curl -X POST "https://app.tuco.ai/api/messages" \ -H "Authorization: Bearer tuco_xxxxxxxxxxxxx" \ -H "Content-Type: application/json" \ -d '{ "message": "Check this out!", "leadId": "667f1f77bcf86cd799439012", "attachmentUrls": ["https://example.com/photo.jpg"] }' ``` *** ## Limits | Limit | Value | | - | - | | Max attachments per message | **2** | | Max file size per attachment | **25 MB** | | Supported sources | Any public URL, UploadThing URLs, Blob URLs belonging to your workspace | > [!TIP] > > **Attachment caching**: When you send the same attachment URL multiple times (e.g. a promo video sent to many leads), Tuco caches it per line. The second send skips download + upload, making delivery significantly faster. *** ## Device gap Each attachment counts as part of a single message — not a separate send. Sending text + video in one API call uses **one** device gap (30s), not two. This is significantly faster than sending them as separate messages. > [!NOTE] > > For automations that send a video followed by a text CTA, combine them into a **single** API call with `message` + `attachmentUrls` instead of two separate calls. This halves your device gap overhead. ## Error responses | Status | When | Body | | - | - | - | | `400` | `attachmentUrls` not an array | `{ "error": "attachmentUrls must be an array" }` | | `400` | More than 2 attachments | `{ "error": "Maximum 2 attachments per message" }` | | `400` | `voiceNote` set but the attachment isn't audio | `{ "code": "VOICE_NOTE_NOT_AUDIO" }` — names the offending file | | `400` | `voiceNote` set with no attachment | `{ "code": "VOICE_NOTE_NO_ATTACHMENT" }` | | `403` | URL doesn't belong to workspace | `{ "error": "Attachment URL does not belong to this organization" }` | | `404` | `leadId` not found in your workspace | `{ "error": "Lead not found or access denied" }` | > [!NOTE] > > Voice-note problems are **not** returned as HTTP errors — the API accepts the send and > the message is marked failed with a reason once the worker evaluates it. Check the > message in your Unibox or via [`GET /api/messages`](/api-reference/endpoint/get-messages). > See [When a voice note will not send](#when-a-voice-note-will-not-send). # Simulate Goal Bot Source: https://docs.tuco.ai/api-reference/endpoint/simulate-goal-bot POST /api/goal-bots/{id}/simulate Run a goal bot against a transcript and see what it would say. Nothing is sent — no message, no draft, no notification. Shows which tools actually ran. > [!NOTE] > > **Nothing leaves the building.** No message is sent, no draft is created, no notification fires > and no booking is made. This is the test chat. Hand the bot a transcript and get back the reply it *would* send. `toolCalls` lists the tools that actually ran, so a bot that only *talks about* checking a calendar is obvious immediately. Also answers on `POST /api/tasks/{id}/simulate`. ## Authentication Pass your workspace API key as a Bearer token, or use a Clerk session token. ```bash theme={null} Authorization: Bearer tuco_xxxxxxxxxxxxx ``` *** ## Path parameter **id** `string` *required* The bot id. A malformed id returns `400 invalid id`. *** ## Request body **messages** `object[]` *required* The transcript, oldest first. At least one message with non-empty content is required — an empty array returns `400 messages are required`. Only the **last 25** messages are used, and each `content` is truncated to **500 characters**. **Message object** **role** `string` *required* `user` (the lead) or `assistant` (the bot). Anything other than `assistant` is read as `user`. **content** `string` *required* What was said. Messages with empty content are dropped. *** ## Example ```bash theme={null} curl -X POST "https://app.tuco.ai/api/goal-bots/6aa9813105bb2cbf5931ac1f/simulate" \ -H "Authorization: Bearer tuco_xxxxxxxxxxxxx" \ -H "Content-Type: application/json" \ -d '{ "messages": [ { "role": "user", "content": "hi, what do you do?" } ] }' ``` ### Success (`200 OK`) ```json theme={null} { "ok": true, "reply": "Hi! We offer a beautiful venue for weddings and events...", "booked": false, "turns": 0, "toolCalls": [], "collected": null } ``` ## Response **ok** `boolean` `true` when the run completed. **reply** `string` What the bot would have sent. **booked** `boolean` Whether the bot would have booked a slot. Nothing is actually booked. **turns** `number` Turns consumed in this run. **toolCalls** `object[]` Tools the bot really invoked, each with its `name`. An empty array means it called nothing. **collected** `object | null` Values matched against `collectFields`, or `null` when none were collected. *** ## Errors | Status | When | Body | | - | - | - | | `400` | Malformed `{id}` | `{ "ok": false, "error": "invalid id" }` | | `400` | `messages` missing, empty, or all blank | `{ "ok": false, "error": "messages are required" }` | | `401` | Missing or invalid API key | `{ "ok": false, "error": "Unauthorized" }` | | `404` | No bot with that id in your workspace | `{ "ok": false, "error": "goal bot not found" }` | | `502` | The model run failed | `{ "ok": false, "error": "run failed" }` | # Invite a Teammate Source: https://docs.tuco.ai/api-reference/endpoint/team-invite POST /api/team/invite Invite someone into a Tuco workspace by email with a role: existing users are added at once, new people get an invite. Uses the workspace API key. > [!NOTE] > > Adds an existing Tuco user to the workspace immediately, or emails an invitation to > someone who does not have an account yet. ## Endpoint * **Method**: `POST` * **Path**: `/api/team/invite` * **Auth**: `Authorization: Bearer tuco_xxxxxxxxxxxxx` ## Body | Field | Type | Required | Notes | | - | - | - | - | | `email` | string | yes | Who to invite | | `role` | string | no | `org:member` (default) or `org:admin` | ## Example request ```bash theme={null} curl https://app.tuco.ai/api/team/invite \ -H "Authorization: Bearer tuco_xxxxxxxxxxxxx" \ -H "Content-Type: application/json" \ -d '{"email": "owner@acmeroofing.com", "role": "org:admin"}' ``` ## Success response (200) ```json theme={null} { "ok": true, "status": "invited", "email": "owner@acmeroofing.com", "inviteUrl": "https://accounts.tuco.ai/v1/tickets/accept?ticket=…", "inviteId": "orginv_…" } ``` | `status` | Meaning | | - | - | | `added` | They already had a Tuco account and are now a member. No email was sent — share the login link yourself | | `invited` | An invitation email was sent. `inviteUrl` is the same link if you want to deliver it your own way | | `already_member` | Nothing to do | ## Permissions A signed-in caller must be a workspace admin. An **API key** is accepted on its own: only a workspace owner or admin can mint one, and it is scoped to this workspace, so the key already carries the authority the check would test. This also means an integration keeps working when the person who created the key changes role or leaves. Agencies: use the workspace key for the workspace you are inviting into — the one returned by [Create Agency Workspace](/api-reference/endpoint/agency-create-workspace). An agency key cannot invite, because "which workspace?" would be ambiguous. ## Error responses | Status | When | | - | - | | `400` | `email` missing, or `role` is not `org:admin` / `org:member`, or no active workspace | | `400` | `code: "INVITE_DOMAIN_BLOCKED"`: the address is on a consumer mail provider we don't send invites to (e.g. qq.com, 163.com). Use the person's work email | | `401` | Missing or invalid key | | `403` | A signed-in non-admin (`code: "ADMIN_REQUIRED"`: only workspace admins can invite), or an agency key (`tucoagency_…`) | | `429` | The workspace already invited 13 people today (`code: "INVITE_DAILY_LIMIT"`). See [Daily limit](#daily-limit) | | `500` | The invitation could not be created | ## Daily limit A workspace can invite up to **13 people per day**. The day resets at 00:00 UTC. Every address counts once it is submitted, whether it ends up `invited`, `added` or `already_member`, and deleting an invitation afterwards does not give the slot back: the email has already been sent. Past the limit the call returns `429` with a `Retry-After` header (seconds until the reset) and nothing is sent: ```json theme={null} { "error": "Invites paused until 2026-11-02T00:00:00.000Z: this many invites in one day looks like automated (bot) activity, so a workspace can invite up to 13 people per day (0 left today). Try again later, or email support@tuco.ai if you need more today.", "code": "INVITE_DAILY_LIMIT", "limit": 13, "used": 13, "remaining": 0, "resetsAt": "2026-11-02T00:00:00.000Z" } ``` Need to bring a larger team in at once? Email [support@tuco.ai](mailto:support@tuco.ai). # Test API Tool Source: https://docs.tuco.ai/api-reference/endpoint/test-tool POST /api/campaign-tools/test Test a Tuco AI API tool with sample arguments before wiring it into a goal bot — returns the live response, latency, and validation errors. > [!NOTE] > > An API tool lets a goal bot call **your** endpoint mid-conversation — check stock, look up an > order, fetch a balance — and use the answer in its reply. Attach a tool to a bot by putting its > `_id` in that bot's `allowedToolIds`. Runs the tool for real against your endpoint and returns both the raw response and the value `responseMapping` pulled out of it. Use it to confirm the mapping before a bot depends on it. > [!WARNING] > > This makes a **real call to your URL**. If the tool is a `POST` that creates something, it will > create it. ## Authentication Pass your workspace API key as a Bearer token, or use a Clerk session token. ```bash theme={null} Authorization: Bearer tuco_xxxxxxxxxxxxx ``` *** ## Request body **toolId** `string` *required* The tool `_id` from [`GET /api/campaign-tools`](/api-reference/endpoint/list-tools). Missing or malformed returns `400 Valid toolId required`. **leadId** `string` Optional. Run the tool with a real lead's data interpolated into the URL and body, so you see exactly what a live conversation would send. An unknown or malformed id is ignored and the tool runs with empty lead data. *** ## Example ```bash theme={null} curl -X POST "https://app.tuco.ai/api/campaign-tools/test" \ -H "Authorization: Bearer tuco_xxxxxxxxxxxxx" \ -H "Content-Type: application/json" \ -d '{ "toolId": "6ac3ed9271adb32c88d566e0", "leadId": "6ac3ea0d71adb32c88d56219" }' ``` ### Success (`200 OK`) ```json theme={null} { "value": "https://httpbin.org/get", "rawResponse": { "args": {}, "headers": { "User-Agent": "node" }, "url": "https://httpbin.org/get" }, "testedWithLeadId": "6ac3ea0d71adb32c88d56219" } ``` ## Response **value** `any` What `responseMapping` resolved to. If this is `null` or missing, the mapping does not match your response shape — fix it with [save-tool](/api-reference/endpoint/save-tool) before attaching the tool to a bot. **rawResponse** `any` The full response your endpoint returned. **testedWithLeadId** `string | null` The lead whose data was interpolated, or `null` when none was used. *** ## Errors | Status | When | Body | | - | - | - | | `400` | `toolId` missing or malformed | `{ "error": "Valid toolId required" }` | | `401` | Missing or invalid API key | `{ "error": "Unauthorized" }` | | `404` | No tool with that id in your workspace | `{ "error": "Tool not found" }` | # Webhook Health Check Source: https://docs.tuco.ai/api-reference/endpoint/test-webhook POST /api/webhooks/{id}/health-check Ping your Tuco webhook endpoint with a minimal signed request to check it is reachable and returns 2xx. Bearer-token REST endpoint. Send a minimal signed request to your endpoint to check it is reachable and responds with `2xx`. To receive realistic payloads for a specific event (attachments, voice notes, P2P SMS, replies…), use [Send test webhook](/api-reference/endpoint/send-test-webhook). The test payload includes `data.test: true` so your handler can distinguish health checks from real events. ## Authentication ```bash theme={null} Authorization: Bearer tuco_xxxxxxxxxxxxx ``` *** ## Path parameters **id** `string` *required* Webhook ID. *** ## What gets sent to your endpoint Tuco sends a real `POST` to your webhook URL with: | Header | Value | | - | - | | `Content-Type` | `application/json` | | `X-Tuco-Signature` | HMAC-SHA256 signature (same as production webhooks) | | `X-Tuco-Event` | First event type from your subscription | | `X-Tuco-Timestamp` | Current ISO timestamp | ```json Test payload your endpoint receives theme={null} { "event": "message.sent", "timestamp": "2026-04-12T12:00:00.000Z", "workspaceId": "org_xxx", "data": { "test": true, "message": "This is a health check test webhook from Tuco AI" } } ``` > [!NOTE] > > The signature is real — computed with your webhook's secret using the same HMAC-SHA256 algorithm as production webhooks. This means your signature verification code gets tested too. *** ## Response **success** `boolean` Whether your endpoint responded with 2xx **message** `string` Human-readable result (on success) **statusCode** `number` HTTP status code from your endpoint **response** `string` Response body from your endpoint **error** `string` Error message (on failure) **details** `string` Error details (on failure) *** ## Examples ```bash theme={null} curl -X POST "https://app.tuco.ai/api/webhooks/680a1b2c3d4e5f6789012345/health-check" \ -H "Authorization: Bearer tuco_xxxxxxxxxxxxx" ``` ```json Healthy endpoint theme={null} { "success": true, "message": "Health check passed", "statusCode": 200, "response": "OK" } ``` ```json Endpoint returned error theme={null} { "success": false, "error": "HTTP 502: Bad Gateway", "details": "upstream connect error", "statusCode": 502 } ``` ```json Endpoint timed out theme={null} { "success": false, "error": "The operation was aborted due to timeout" } ``` > [!WARNING] > > The test has a **10-second timeout**. If your endpoint takes longer, it'll report a timeout failure. Make sure your handler returns `2xx` quickly and does heavy processing asynchronously. # Unenroll Lead Source: https://docs.tuco.ai/api-reference/endpoint/unenroll-lead DELETE /api/goal-bots/{id}/enroll Unenroll a lead from a Tuco AI goal bot — stops further AI replies and cancels scheduled messages while preserving conversation history. > [!WARNING] > > **Instruction bots are being retired.** They are the older stage-based engine: a lead is > *enrolled* into one and walks a sequence of stages. The engine that replaced them — > [goal bots](/api-reference/endpoint/list-goal-bots) — has no stages and no enrolment: you tag a > lead and the bot handles their replies. > > Build new work on goal bots. These endpoints stay up for integrations already using them. Takes a lead back out of an instruction bot. Conversation history is preserved — only the enrolment state is cleared, so the bot stops picking the lead up. Also answers on `DELETE /api/instructions/{id}/enroll`. > [!NOTE] > > **Goal bots do not use this endpoint.** To stop a goal bot handling a lead, remove its trigger tag > with [`PATCH /api/leads/{id}`](/api-reference/endpoint/update-lead). ## Authentication Pass your workspace API key as a Bearer token, or use a Clerk session token. ```bash theme={null} Authorization: Bearer tuco_xxxxxxxxxxxxx ``` *** ## Path parameter **id** `string` *required* The **instruction** id the lead is currently enrolled in. A malformed id returns `400 Invalid instruction ID`. *** ## Request body **leadId** `string` *required* The lead to unenrol. Missing or malformed returns `400 Valid leadId is required`. > [!WARNING] > > `DELETE` here **has a request body**. Some HTTP clients drop bodies on `DELETE` by default — if > you get `400 Valid leadId is required` with a `leadId` you know is correct, that is why. *** ## Example ```bash theme={null} curl -X DELETE "https://app.tuco.ai/api/goal-bots/6a970c3429603484fb08b211/enroll" \ -H "Authorization: Bearer tuco_xxxxxxxxxxxxx" \ -H "Content-Type: application/json" \ -d '{ "leadId": "6ac3ea0d71adb32c88d56219" }' ``` ### Success (`200 OK`) ```json theme={null} { "success": true, "message": "Lead unenrolled from instruction" } ``` The lead's stage, turn counter, collected fields and enrolment timestamp are cleared, and the instruction's `stats.inProgress` decrements. *** ## Errors | Status | When | Body | | - | - | - | | `400` | Malformed `{id}` | `{ "error": "Invalid instruction ID" }` | | `400` | `leadId` missing or malformed | `{ "error": "Valid leadId is required" }` | | `400` | Lead is not enrolled in **this** instruction | `{ "error": "Lead is not enrolled in this instruction" }` | | `401` | Missing or invalid API key | `{ "error": "Unauthorized" }` | | `404` | Lead not in your workspace | `{ "error": "Lead not found" }` | # Update Fallback SMS Config Source: https://docs.tuco.ai/api-reference/endpoint/update-fallback-config PATCH /api/workspace/fallback-config Change where backup SMS is sent when iMessage fails, including connecting your own Telnyx account. Bearer-token auth, JSON request and response. > [!NOTE] > > Everything on the **Settings → Fallbacks** page is available here, so backup SMS can be set up > entirely over the API without opening the dashboard. > > A backup text goes out when iMessage cannot deliver, for two separate reasons: the send failed > technically, or the recipient has no iMessage. Both use the same destination. Send only the fields you want to change. **Omitting a credential leaves the stored one untouched**, so you can change the number without re-sending keys. Setting `telnyxUseOwnAccount` to `false` deletes them. ## Authentication Pass your workspace API key as a Bearer token, or use a Clerk session token. ```bash theme={null} Authorization: Bearer tuco_xxxxxxxxxxxxx ``` *** ## Request body **fallbackDestination** `string` `none`, `ghl`, `twilio` or `telnyx`. `none` turns backup texts off entirely. **telnyxFromNumber** `string` E.164. The number backup texts are sent from, and where replies come back to. **telnyxUseOwnAccount** `boolean` (default: false) Send on your own Telnyx account instead of Tuco's, keeping the number, the 10DLC registration and the billing under your brand. Setting this to `false` deletes any stored credentials. **telnyxApiKey** `string` **Write only.** Telnyx portal → Account → API Keys. Never returned by `GET`. **telnyxPublicKey** `string` **Write only.** Telnyx portal → Account → Public Key. Without it, replies from your leads are rejected as unverified. **sendFallbackSmsOnFailed** `boolean` Also fall back on a technical send failure, not only when the recipient has no iMessage. Setting this before a destination is configured returns `FALLBACK_NOT_CONFIGURED`. **dailyLimitOverflow** `string` `reschedule` or `fallback` — what to do when the line hits its daily cap. *** ## Examples ```bash Use Tuco's Telnyx account theme={null} curl -X PATCH "https://app.tuco.ai/api/workspace/fallback-config" \ -H "Authorization: Bearer tuco_xxxxxxxxxxxxx" \ -H "Content-Type: application/json" \ -d '{ "fallbackDestination": "telnyx", "telnyxFromNumber": "+13055550142", "sendFallbackSmsOnFailed": true }' ``` ```bash Use your own Telnyx account theme={null} curl -X PATCH "https://app.tuco.ai/api/workspace/fallback-config" \ -H "Authorization: Bearer tuco_xxxxxxxxxxxxx" \ -H "Content-Type: application/json" \ -d '{ "fallbackDestination": "telnyx", "telnyxUseOwnAccount": true, "telnyxApiKey": "KEY0197...", "telnyxPublicKey": "base64publickey...", "telnyxFromNumber": "+13055550142", "sendFallbackSmsOnFailed": true }' ``` ```bash Go back to Tuco's account theme={null} curl -X PATCH "https://app.tuco.ai/api/workspace/fallback-config" \ -H "Authorization: Bearer tuco_xxxxxxxxxxxxx" \ -H "Content-Type: application/json" \ -d '{ "fallbackDestination": "telnyx", "telnyxUseOwnAccount": false }' ``` ### Success (`200 OK`) ```json theme={null} { "success": true, "fallbackDestination": "telnyx", "sendFallbackSmsOnFailed": true } ``` Read the full config back with [`GET /api/workspace/fallback-config`](/api-reference/endpoint/fallback-config). *** ## Using your own Telnyx account Both keys are required together. The API key is checked with Telnyx before anything is stored, including that `telnyxFromNumber` is a number on that account — so a wrong key fails here rather than the first time a text needs to go out. Replies only reach you once Telnyx knows where to send them. In Telnyx, go to **Messaging → Messaging Profiles → your profile → Inbound Settings**, set the **Webhook URL** to: ``` https://app.tuco.ai/api/webhooks/telnyx-inbound ``` and set **API version** to `2`. The URL is the same for everyone; replies are matched to you by `telnyxFromNumber`. *** ## Send a test Sends a real text through the **saved** settings, so it proves the credentials and the number together. Save first — it reads what is stored, not what you pass. **destination** `string` *required* Which destination to test: `ghl`, `twilio`, `telnyx` or `custom_webhook`. **testPhone** `string` E.164 number to send the test text to. Required for `ghl`, `twilio` and `telnyx`. ```bash theme={null} curl -X POST "https://app.tuco.ai/api/workspace/fallback-config/test" \ -H "Authorization: Bearer tuco_xxxxxxxxxxxxx" \ -H "Content-Type: application/json" \ -d '{ "destination": "telnyx", "testPhone": "+13055550199" }' ``` ```json theme={null} { "ok": true, "destination": "telnyx", "details": { "sentTo": "+13055550199", "account": "your Telnyx account" } } ``` `details.account` tells you which account it actually went out on, so you can confirm you are on your own rather than Tuco's. *** ## Error codes Returned on `PATCH` as `{ "error": "...", "code": "..." }`. | Code | Meaning | | - | - | | `TELNYX_KEY_INVALID` | Telnyx rejected the API key | | `TELNYX_NUMBER_NOT_ON_ACCOUNT` | The key is valid but `telnyxFromNumber` is not on that account | | `TELNYX_CREDENTIALS_INCOMPLETE` | `telnyxUseOwnAccount` is `true` but a key is missing | | `TELNYX_UNREACHABLE` | Telnyx could not be reached to verify the key | | `TELNYX_ERROR` | Telnyx returned an unexpected status while verifying the key | | `ENCRYPTION_NOT_CONFIGURED` | Credentials cannot be stored safely — contact support | | `FALLBACK_NOT_CONFIGURED` | `sendFallbackSmsOnFailed` was set before a destination was configured | | `INVALID_URL` | `customWebhookUrl` is not a valid URL | # Update Goal Bot Source: https://docs.tuco.ai/api-reference/endpoint/update-goal-bot PATCH /api/goal-bots/{id} Change a goal bot's prompt, tools, tags, tone, or status. Takes any subset of the create fields and returns the updated bot. > [!NOTE] > > **Goal bots and task agents are the same object.** The two engines merged; `/api/goal-bots` > and `/api/tasks` are aliases over one collection and return identical bodies. Every response > carries both `goalBot` and `taskAgent` (or `goalBots` and `taskAgents`) so integrations written > against either name keep working. > > The older stage-based engine moved to [`/api/instructions`](/api-reference/endpoint/list-instruction-bots) > and is being retired. Send **only the fields you want to change**. Anything you leave out keeps its current value — there are no defaults applied on update. Array fields (`includeTags`, `excludeTags`, `allowedToolIds`, `collectFields`) **replace** the stored array, so send the complete set. ## Authentication Pass your workspace API key as a Bearer token, or use a Clerk session token. ```bash theme={null} Authorization: Bearer tuco_xxxxxxxxxxxxx ``` *** ## Path parameter **id** `string` *required* The bot id. A malformed id returns `400 Invalid id`. *** ## Request body Every field is optional. Unknown fields are ignored. **name** `string` Display name for the bot. An empty or missing name returns `400 Name is required`. **prompt** `string` The instructions the model runs on — who it is, what it is trying to do, what it must not say. An empty or missing prompt returns `400 Prompt is required`. **includeTags** `string[]` Tags that wake this bot. A lead carrying any of them is handled by this bot when it replies. Set tags with [`PATCH /api/leads/{id}`](/api-reference/endpoint/update-lead). Defaults to `[]`. **excludeTags** `string[]` Tags that keep a lead away from this bot, even when `includeTags` matches. Defaults to `[]`. **mode** `string` (default: autopilot) How replies are delivered. | Value | Behaviour | | - | - | | `autopilot` | The bot replies on its own. | | `copilot` | Every reply is saved as a draft for a human to approve. | | `manual` | The bot is off. This is the only way to stop the built-in **Auto Replies** bot, which cannot be deleted. | | `draft` | Legacy alias for `copilot`, still accepted. | > [!WARNING] > > An unrecognised value is **not** rejected — it is silently stored as `copilot`. Read the > `mode` back from the response to confirm what was saved. **status** `string` (default: active) `active` or `paused`. A new bot goes live the moment it exists and starts answering leads whose tags already match, so pass `"paused"` when you want to create, inspect, then flip it on with [`PATCH`](/api-reference/endpoint/update-goal-bot). Any value other than `"paused"` is stored as `active`. **connector** `string` (default: calendly) Calendar used for booking: `calendly` or `ghl_calendar`. Any other value falls back to `calendly`. **kbRetrieval** `string` (default: always) When the bot searches your knowledge base. `always` searches on every inbound message; `auto` leaves the decision to the model. On create, anything other than `"auto"` is stored as `always`. **tone** `string` Free-text tone hint, e.g. `"warm and brief"`. **canAsk** `boolean` (default: true) Whether the bot may ask the lead follow-up questions. Only an explicit `false` turns it off. **typingIndicator** `boolean` (default: true) Send a typing signal before replying. Only an explicit `false` turns it off. **maxTurns** `number` (default: 8) How many times the bot may reply in one conversation. Clamped to `1`–`20`; a non-numeric or non-positive value falls back to `8`. **onDoneTag** `string` Tag applied to the lead when the bot reaches its goal. **writeTagToCrm** `boolean` (default: false) Push `onDoneTag` to the connected CRM as well as to Tuco. Only an explicit `true` enables it. **allowedToolIds** `string[]` Ids of the API tools this bot may call, from [`GET /api/campaign-tools`](/api-reference/endpoint/list-tools). Omit to allow none. **collectFields** `string[]` Field names the bot should try to collect during the conversation, e.g. `["email", "company"]`. > [!WARNING] > > `kbRetrieval` behaves as the **mirror** of create here: on `PATCH`, anything other than the exact > string `"always"` is stored as `"auto"`. Send `"always"` explicitly if that is what you want. *** ## Example ```bash theme={null} curl -X PATCH "https://app.tuco.ai/api/goal-bots/6aa9813105bb2cbf5931ac1f" \ -H "Authorization: Bearer tuco_xxxxxxxxxxxxx" \ -H "Content-Type: application/json" \ -d '{ "status": "paused", "maxTurns": 4 }' ``` Turning the built-in **Auto Replies** bot off: ```bash theme={null} curl -X PATCH "https://app.tuco.ai/api/goal-bots/6aa9813105bb2cbf5931ac1f" \ -H "Authorization: Bearer tuco_xxxxxxxxxxxxx" \ -H "Content-Type: application/json" \ -d '{ "mode": "manual" }' ``` ### Success (`200 OK`) ```json theme={null} { "success": true, "goalBot": { /* the full updated bot */ }, "taskAgent": { /* identical object */ } } ``` *** ## Errors | Status | When | Body | | - | - | - | | `400` | Malformed `{id}` | `{{ "error": "Invalid id" }}` | | `400` | Key has no active workspace | `{{ "error": "No active workspace" }}` | | `401` | Missing or invalid API key | `{{ "error": "Unauthorized" }}` | | `404` | No bot with that id in your workspace | `{{ "error": "Not found" }}` | # Update Lead Source: https://docs.tuco.ai/api-reference/endpoint/update-lead PATCH /api/leads/{id} Update a lead's details or tags. Tags are what trigger your bots — a goal bot wakes on the tags listed in its includeTags. > [!NOTE] > > **Tags are the wiring.** A goal bot wakes on the tags in its `includeTags`, so adding a tag here is > how you put a lead in front of a bot from a script. See > [`PATCH /api/goal-bots/{id}`](/api-reference/endpoint/update-goal-bot). Send only the fields you want to change. Anything you leave out is untouched. ## Authentication Pass your workspace API key as a Bearer token, or use a Clerk session token. ```bash theme={null} Authorization: Bearer tuco_xxxxxxxxxxxxx ``` *** ## Path parameter **id** `string` *required* The lead id. A malformed id returns `400 Invalid lead id`. *** ## Request body Exactly seven fields are writable. **Anything else in the body is ignored** — including `phone`, which is set when the lead is created and cannot be changed here. **tags** `string[]` **Replaces** the whole tag array — send the complete set, not a delta. Values are trimmed, de-duplicated, and blanks are dropped. Maximum **50** tags. A non-array returns `400 tags must be an array of strings`; more than 50 returns `400 A lead can carry at most 50 tags`. **firstName** `string` First name. Trimmed. Pass `null` to clear it to an empty string. **lastName** `string` Last name. Trimmed. Pass `null` to clear it. **email** `string` Email address. Trimmed. Pass `null` to clear it. **companyName** `string` Company name. Trimmed. Pass `null` to clear it. **notes** `string` Free-text notes about the lead. Trimmed. Pass `null` to clear it. **Not inert** — your bots read this. A task agent sees it through `get_lead_details`, and message personalization can reference it, so anything you write here can end up shaping a reply. **customFields** `object` **Replaces** the whole custom-field object. Pass `null` to clear it to `{}`. An array or a non-object returns `400 customFields must be an object`. Read the keys already in use with `GET /api/leads/custom-field-keys`. > [!WARNING] > > A body with **none** of these six fields returns `400` — there is nothing to update. An empty > object `{}` counts as nothing. *** ## Example — tag a lead so a bot picks it up ```bash theme={null} curl -X PATCH "https://app.tuco.ai/api/leads/6ac3ea0d71adb32c88d56219" \ -H "Authorization: Bearer tuco_xxxxxxxxxxxxx" \ -H "Content-Type: application/json" \ -d '{ "tags": ["demo-requested", "enterprise"] }' ``` ## Example — update details ```bash theme={null} curl -X PATCH "https://app.tuco.ai/api/leads/6ac3ea0d71adb32c88d56219" \ -H "Authorization: Bearer tuco_xxxxxxxxxxxxx" \ -H "Content-Type: application/json" \ -d '{ "firstName": "Jane", "companyName": "Acme Corp", "customFields": { "industry": "Technology" } }' ``` ### Success (`200 OK`) Returns the full updated lead — the same shape as [`GET /api/leads/{id}`](/api-reference/endpoint/get-lead). ```json theme={null} { "lead": { "_id": "6ac3ea0d71adb32c88d56219", "firstName": "Jane", "lastName": "Doe", "phone": "+14152004145", "email": "jane@example.com", "companyName": "Acme Corp", "tags": ["demo-requested", "enterprise"], "customFields": { "industry": "Technology" }, "updatedAt": "2026-10-05T18:48:02.917Z" } } ``` *** ## Errors | Status | When | Body | | - | - | - | | `400` | Malformed `{id}` | `{ "error": "Invalid lead id" }` | | `400` | Body is not a JSON object | `{ "error": "Body must be a JSON object" }` | | `400` | No editable field supplied | `{ "error": "Nothing to update. Editable fields: firstName, lastName, email, companyName, notes, tags, customFields" }` | | `400` | `tags` not an array of strings | `{ "error": "tags must be an array of strings" }` | | `400` | More than 50 tags | `{ "error": "A lead can carry at most 50 tags" }` | | `400` | `customFields` not an object | `{ "error": "customFields must be an object" }` | | `400` | A string field was sent as a number or object | `{ "error": "firstName must be a string" }` | | `401` | Missing or invalid API key | `{ "error": "Unauthorized" }` | | `404` | No lead with that id in your workspace | `{ "error": "Lead not found" }` | # Update a Line Source: https://docs.tuco.ai/api-reference/endpoint/update-line PATCH /api/lines/{id} Change a line's name, photo or call forwarding number, or turn on a call recording notice. Tuco AI iMessage API, bearer-token auth, JSON. > [!NOTE] > > Updates a line's display profile (`firstName`, `lastName`, `profileImageUrl`), its [call forwarding number](#call-forwarding) (`forwardCallsTo`) and its [call recording notice](#call-recording-notice) (`callRecordingDisclosure`, `callRecordingDisclosureMessage`). Send only the fields you want to change. Get the line `_id` from [Get All Lines](/api-reference/endpoint/get-lines). ## Endpoint * **Method**: `PATCH` * **Path**: `/api/lines/{id}` * **Auth**: `Authorization: Bearer tuco_xxxxxxxxxxxxx` ## Body | Field | Type | Notes | | - | - | - | | `firstName` | string | Optional. Trimmed, cannot be blank, max 100 characters. | | `lastName` | string | Optional. Trimmed, cannot be blank, max 100 characters. | | `profileImageUrl` | string \| null | Optional. A public `http(s)` URL to the photo, max 2048 characters. Send `null` to remove the photo. | | `forwardCallsTo` | string \| null | Optional. The number inbound calls to this line are forwarded to, with country code, e.g. `+14155550123`. Stored in E.164 format. Must be in the same country as the line's eSIM and can't be the line's own number. Send `null` (or an empty string) to stop forwarding. Phone lines only. See [Call forwarding](#call-forwarding). | | `callRecordingDisclosure` | boolean | Optional. `true` plays a short "this call may be recorded" notice when the person you call answers. `false` turns it off. Off by default. Phone lines only. See [Call recording notice](#call-recording-notice). | | `callRecordingDisclosureMessage` | string \| null | Optional. Your own wording for the notice, max 300 characters. Send `null` (or an empty string) to go back to the default: *"This call may be recorded for quality and training purposes."* | Send at least one field. Any other field (for example `dailyTotalMessagesLimit`) is rejected with `400` and nothing is changed. > [!WARNING] > > **3 line info changes per line per month.** Each change to the name, photo or call forwarding number needs a person on our side to update the line, so a line's info can change at most **3 times per calendar month (UTC)**. One request that changes several of them counts once. The 4th returns `400` with `"code": "LINE_INFO_UPDATE_LIMIT"` and nothing is changed — contact [support@tuco.ai](mailto:support@tuco.ai). Sending the same values the line already has doesn't count, and the name, photo and forwarding number you set when ordering the line are free. Every response includes `lineInfoUpdates` so you can see how many changes are left. Review everything and be sure before you send. Turning the call recording notice on or off, or changing its wording, does **not** count toward this limit. > [!TIP] > > Tuco stores the photo **link** you send — it does not copy the image. Host the photo somewhere permanent; if the link stops working, the photo stops showing. ## Example request ```bash theme={null} curl -X PATCH https://app.tuco.ai/api/lines/699f704bc405fae6ca299a08 \ -H "Authorization: Bearer tuco_xxxxxxxxxxxxx" \ -H "Content-Type: application/json" \ -d '{ "firstName": "Sarah", "lastName": "Lee", "profileImageUrl": "https://cdn.example.com/sarah.png" }' ``` Remove the photo: ```bash theme={null} curl -X PATCH https://app.tuco.ai/api/lines/699f704bc405fae6ca299a08 \ -H "Authorization: Bearer tuco_xxxxxxxxxxxxx" \ -H "Content-Type: application/json" \ -d '{ "profileImageUrl": null }' ``` ## Call forwarding Calls to the line's own number ring the number you set in `forwardCallsTo`: ```bash theme={null} curl -X PATCH https://app.tuco.ai/api/lines/699f704bc405fae6ca299a08 \ -H "Authorization: Bearer tuco_xxxxxxxxxxxxx" \ -H "Content-Type: application/json" \ -d '{ "forwardCallsTo": "+14155550123" }' ``` * **Same country as the eSIM.** A US line forwards to a US number, a Canadian line to a Canadian number. * **Not the line's own number.** Calls would loop back to the line. * **Takes effect** once our team applies it to the line. The change is saved right away and the team is told at the same time. * **Stop forwarding:** send `{ "forwardCallsTo": null }`. You can also change it in the dashboard: **Lines → Edit** on the line. ## Call recording notice Every outbound call placed through Tuco is recorded. If you need the person you call to be told, turn on the notice for the line that places your calls: ```bash theme={null} curl -X PATCH https://app.tuco.ai/api/lines/699f704bc405fae6ca299a08 \ -H "Authorization: Bearer tuco_xxxxxxxxxxxxx" \ -H "Content-Type: application/json" \ -d '{ "callRecordingDisclosure": true }' ``` Use your own wording (optional): ```bash theme={null} curl -X PATCH https://app.tuco.ai/api/lines/699f704bc405fae6ca299a08 \ -H "Authorization: Bearer tuco_xxxxxxxxxxxxx" \ -H "Content-Type: application/json" \ -d '{ "callRecordingDisclosureMessage": "Hi, this is Acme. This call is recorded for quality." }' ``` How it works: * **When:** the moment the person you call picks up, before anyone talks. It takes about 3–5 seconds. * **Who hears it:** the person you call **and** your rep, so your rep knows to let it finish. * **On the recording:** yes. The notice is at the start of the call recording, so you have proof it played. * **Which calls:** every call this line places **through Tuco**: the dashboard dialer, [Place a Call](/api-reference/endpoint/place-call), and calls made from your CRM through Tuco. It also plays when the call goes out from a [Registered caller ID](/api-reference/endpoint/calling-addons) number. * **Not covered:** calls on the FaceTime Audio add-on, and calls you make from your own phone. Those don't go through Tuco's calling, so there is nothing to play the notice into. * **Takes effect:** on the next call that's answered. It's free. You can also turn it on in the dashboard: **Lines → Calling** on the line. > [!NOTE] > > Whether a notice like this meets the recording-consent rules where you and the people you call are > (for example, US states that require all parties to consent) is your call. Check with your own counsel. ## Success response (200) Returns the updated line, in the same shape as an item from [Get All Lines](/api-reference/endpoint/get-lines), plus `lineInfoUpdates`: how many line info changes (name, photo, forwarding number) this line has used and has left this month. ```json theme={null} { "line": { "_id": "699f704bc405fae6ca299a08", "workspaceId": "org_3ABCDbdGyF6w99hikyVN4cmo6H0", "phone": "+16465550100", "firstName": "Sarah", "lastName": "Lee", "profileImageUrl": "https://cdn.example.com/sarah.png", "forwardCallsTo": "+14155550123", "callRecordingDisclosure": true, "isActive": true, "provisioningStatus": "active", "updatedAt": "2026-10-19T11:05:12.000Z" }, "lineInfoUpdates": { "limitPerMonth": 3, "usedThisMonth": 1, "remainingThisMonth": 2 } } ``` ## Error responses | Status | When | Body | | - | - | - | | `400` | Invalid line id | `{ "error": "Invalid line id" }` | | `400` | Unsupported field in body | `{ "error": "Only firstName, lastName, profileImageUrl, callRecordingDisclosure, callRecordingDisclosureMessage, forwardCallsTo can be updated. Unsupported: " }` | | `400` | Empty body | `{ "error": "Provide at least one of firstName, lastName, profileImageUrl, callRecordingDisclosure, callRecordingDisclosureMessage, forwardCallsTo" }` | | `400` | Blank or non-string name | `{ "error": "firstName must be a non-empty string" }` | | `400` | Bad photo URL | `{ "error": "profileImageUrl must be an http(s) URL or null" }` | | `400` | Notice toggle not a boolean | `{ "error": "callRecordingDisclosure must be true or false" }` | | `400` | Notice text not a string, or over 300 characters | `{ "error": "callRecordingDisclosureMessage must be at most 300 characters" }` | | `400` | Notice on an email line | `{ "error": "callRecordingDisclosure applies to phone lines only — email lines place no calls" }` | | `400` | Forwarding number isn't a phone number | `{ "error": "forwardCallsTo must be a valid phone number with country code, e.g. +14155550123" }` | | `400` | Forwarding to the line's own number | `{ "error": "forwardCallsTo can't be the line's own number — calls would loop back to it" }` | | `400` | Forwarding number in another country | `{ "error": "forwardCallsTo must be a United States number to match the line's eSIM country (got CA)" }` | | `400` | Forwarding on an email line | `{ "error": "forwardCallsTo applies to phone lines only — email lines take no calls" }` | | `400` | Line info already changed 3 times this month | `{ "error": "This line's info has already been changed 3 times this month… contact support@tuco.ai…", "code": "LINE_INFO_UPDATE_LIMIT", "limitPerMonth": 3, "lineInfoUpdates": { "limitPerMonth": 3, "usedThisMonth": 3, "remainingThisMonth": 0 } }` | | `401` | Missing or invalid API key | `{ "error": "Unauthorized" }` | | `402` | Agency workspace with unpaid billing | `{ "error": "Editing lines is paused while your agency billing is unpaid. ..." }` | | `404` | Line not found in your workspace | `{ "error": "Line not found" }` | | `500` | Server error | `{ "error": "Internal server error" }` | *** Use the **Try it** panel to run this request interactively. # Update Task Agent Source: https://docs.tuco.ai/api-reference/endpoint/update-task-agent PATCH /api/tasks/{id} Update a Tuco task agent's prompt, tags, connector or status. Send only the fields to change; array fields replace the stored array in full. > [!NOTE] > > **This is an alias.** `PATCH /api/tasks/{id}` and > [`PATCH /api/goal-bots/{id}`](/api-reference/endpoint/update-goal-bot) are the same route. Send only the fields you want to change — anything omitted keeps its current value. Array fields **replace** the stored array, so send the complete set. ## Authentication Pass your workspace API key as a Bearer token, or use a Clerk session token. ```bash theme={null} Authorization: Bearer tuco_xxxxxxxxxxxxx ``` *** ## Path parameter **id** `string` *required* The agent id. A malformed id returns `400 Invalid id`. *** ## Request body Every field is optional; unknown fields are ignored. **name** `string` Display name. **prompt** `string` The instructions the model runs on. **includeTags** `string[]` Replaces the tag list that wakes this agent. **excludeTags** `string[]` Replaces the exclusion list. **mode** `string` `autopilot`, `copilot`, `manual`, or the legacy alias `draft`. Omit to leave unchanged. An unrecognised value is stored as `copilot` rather than rejected. **status** `string` `active` or `paused`. Anything other than `"paused"` is read as `active`. **connector** `string` `calendly` or `ghl_calendar`. **kbRetrieval** `string` `always` or `auto`. On `PATCH`, anything other than the exact string `"always"` is stored as `"auto"` — the mirror of create, so send `"always"` explicitly when that is what you want. **tone** `string` Free-text tone hint. **canAsk** `boolean` Only an explicit `false` turns it off. **typingIndicator** `boolean` Only an explicit `false` turns it off. **maxTurns** `number` Clamped to 1–20; a non-numeric value falls back to 8. **onDoneTag** `string` Tag applied when the agent finishes. **writeTagToCrm** `boolean` Only an explicit `true` enables it. **allowedToolIds** `string[]` Replaces the allowed-tool list. **collectFields** `string[]` Replaces the collect list. *** ## Example ```bash theme={null} curl -X PATCH "https://app.tuco.ai/api/tasks/6aa9813105bb2cbf5931ac1f" \ -H "Authorization: Bearer tuco_xxxxxxxxxxxxx" \ -H "Content-Type: application/json" \ -d '{ "status": "paused", "maxTurns": 4 }' ``` ### Success (`200 OK`) ```json theme={null} { "success": true, "goalBot": { /* the full updated agent */ }, "taskAgent": { /* identical object */ } } ``` *** ## Errors | Status | When | Body | | - | - | - | | `400` | Malformed `{id}` | `{ "error": "Invalid id" }` | | `400` | Key has no active workspace | `{ "error": "No active workspace" }` | | `401` | Missing or invalid API key | `{ "error": "Unauthorized" }` | | `404` | No agent with that id in your workspace | `{ "error": "Not found" }` | # Update Webhook Source: https://docs.tuco.ai/api-reference/endpoint/update-webhook PATCH /api/webhooks/{id} Update a Tuco webhook's URL, subscribed events, name or active status. Send only the fields you want to change. Bearer-token REST endpoint. Update any combination of fields on an existing webhook. Only include the fields you want to change. ## Authentication ```bash theme={null} Authorization: Bearer tuco_xxxxxxxxxxxxx ``` *** ## Path parameters **id** `string` *required* Webhook ID. *** ## Request body All fields are optional. Include only what you want to change. **url** `string` New endpoint URL. **events** `string[]` New event subscriptions. **Replaces** the existing list (not a merge). Valid values: `message.sent`, `message.failed`, `message.fallback`, `message.reply`, `message.reaction`, `message.opened`, `message.ai_draft`, `message.ai_draft_approved`, `message.ai_draft_rejected`, `conversation.handover`, `call.recording.ready`, `dnc.added`, `group.message.received`, `group.message.sent`, `group.message.failed`, `group.message.reaction`. **name** `string` New name. **description** `string` New description. **isActive** `boolean` Set `false` to pause delivery without deleting the webhook. Set `true` to resume. *** ## Examples ```bash Disable webhook theme={null} curl -X PATCH "https://app.tuco.ai/api/webhooks/680a1b2c3d4e5f6789012345" \ -H "Authorization: Bearer tuco_xxxxxxxxxxxxx" \ -H "Content-Type: application/json" \ -d '{ "isActive": false }' ``` ```bash Change URL theme={null} curl -X PATCH "https://app.tuco.ai/api/webhooks/680a1b2c3d4e5f6789012345" \ -H "Authorization: Bearer tuco_xxxxxxxxxxxxx" \ -H "Content-Type: application/json" \ -d '{ "url": "https://new-endpoint.example.com/webhooks" }' ``` ```bash Change events theme={null} curl -X PATCH "https://app.tuco.ai/api/webhooks/680a1b2c3d4e5f6789012345" \ -H "Authorization: Bearer tuco_xxxxxxxxxxxxx" \ -H "Content-Type: application/json" \ -d '{ "events": ["message.reply", "message.opened"] }' ``` ```json 200 Response theme={null} { "success": true } ``` *** ## Errors | Status | When | | - | - | | `400` | Invalid URL, empty events array, invalid event types, empty name | | `401` | Invalid or missing API key | | `402` | Subscription past due | | `404` | Webhook not found in your workspace | # Webhooks Overview Source: https://docs.tuco.ai/api-reference/endpoint/webhook Register endpoints, manage subscriptions, and test delivery — all via API. REST endpoint in the Tuco AI iMessage API — bearer-token auth, JSON. ## What are webhooks? Webhooks push real-time event notifications to URLs you control. Instead of polling the API, your systems receive a `POST` request the moment something happens — a message sends, fails, gets a reply, or is read. *** ## How it works **1. Register a webhook** Call [Create Webhook](/api-reference/endpoint/create-webhook) with your endpoint URL and the events you care about. **Save the signing secret** from the response — it's shown once. **2. Receive events** Tuco sends a signed `POST` to your URL whenever a subscribed event fires. Verify the `X-Tuco-Signature` header using your secret. **3. Return 2xx quickly** Acknowledge the webhook with a `2xx` response within a few seconds. Do heavy processing asynchronously. *** ## Available events | Event | Fired when | | - | - | | `message.sent` | Message accepted and sent by Tuco | | `message.failed` | Message failed after all retries (technical error) | | `message.fallback` | Recipient doesn't have iMessage (business outcome, not error) | | `message.reply` | Lead or contact replied to your message | | `message.opened` | Message was read (read receipt, where supported) | See [Message Webhooks](/api-reference/message-webhooks) for full payload details, example bodies, and field-by-field documentation for each event. *** ## Management API Full CRUD for webhook registrations. All endpoints require Bearer token auth. > [card] [List Webhooks](/api-reference/endpoint/list-webhooks) > > `GET /api/webhooks` — See all webhooks in your workspace > [card] [Create Webhook](/api-reference/endpoint/create-webhook) > > `POST /api/webhooks` — Register a new endpoint > [card] [Get Webhook](/api-reference/endpoint/get-webhook) > > `GET /api/webhooks/{id}` — Get details for one webhook > [card] [Update Webhook](/api-reference/endpoint/update-webhook) > > `PATCH /api/webhooks/{id}` — Change URL, events, or status > [card] [Delete Webhook](/api-reference/endpoint/delete-webhook) > > `DELETE /api/webhooks/{id}` — Remove a webhook permanently > [card] [Test Webhook](/api-reference/endpoint/test-webhook) > > `POST /api/webhooks/{id}/health-check` — Fire a test ping *** ## Security Every webhook `POST` includes three headers for verification: | Header | Purpose | | - | - | | `X-Tuco-Signature` | HMAC-SHA256 hex digest of the request body, signed with your webhook secret | | `X-Tuco-Event` | Event type (e.g. `message.sent`) | | `X-Tuco-Timestamp` | When the webhook was fired (ISO UTC) | Always verify `X-Tuco-Signature` before processing. See [signature verification code examples](/api-reference/message-webhooks#headers--signature-verification) in the Message Webhooks page. *** ## Delivery behavior > [!NOTE] > > Webhooks are **fire-and-forget**. Tuco sends each event once and does not retry on failure. Make sure your endpoint is reliable and returns `2xx` quickly. * **Parallel delivery** — if you have multiple webhooks subscribed to the same event, all receive the POST simultaneously * **10-second timeout** — if your endpoint doesn't respond within 10 seconds, the delivery is marked as failed * **No retry** — failed deliveries are logged but not retried. Use the [Test Webhook](/api-reference/endpoint/test-webhook) endpoint to verify your setup * **Failure tracking** — `failureCount`, `lastSuccessAt`, and `lastFailureAt` on the webhook object let you monitor health > [!TIP] > > Use [Test Webhook](/api-reference/endpoint/test-webhook) after creating or updating a webhook to confirm your endpoint is reachable and your signature verification works. # Errors & Status Codes Source: https://docs.tuco.ai/api-reference/errors HTTP status codes, error formats, and what to do when things go wrong. Part of the Tuco AI iMessage API reference — bearer-token auth, JSON responses, examples. ## Error format All error responses return a JSON body with an `error` field. Some include a machine-readable `code` for programmatic handling. ```json theme={null} { "error": "Human-readable description of the problem", "code": "MACHINE_READABLE_CODE" } ``` *** ## HTTP status codes | Code | Meaning | | - | - | | **200** | Request succeeded | | **201** | Resource created (e.g. message, lead) | | **400** | Validation error — check the `error` field for details | | **401** | Authentication failed — invalid or missing API key | | **402** | Workspace is read-only (e.g. subscription past due) | | **404** | Resource not found (e.g. lead, line, message) | | **429** | Rate limit exceeded — wait and retry | | **500** | Internal server error — retry or contact support | *** ## Send Message errors (`POST /api/messages`) These are the specific errors you may encounter when sending a message. > [!NOTE] > > Pre-send checks like line limits, time windows, device gaps, and contact gaps > **never** return errors. The message is accepted with `201` and the `status` > field indicates the outcome (`pending`, `scheduled`, etc.). > [accordion] 400 — Message and attachments both empty > > Neither `message` nor `attachmentUrls` was provided (or both were empty). > > ```json theme={null} > { "error": "Message and attachmentUrls cannot both be empty" } > ``` > > **Fix:** Include at least one of: a non-empty `message` string, or an `attachmentUrls` array with up to 2 URLs. > [accordion] 400 — Invalid messageType > > The `messageType` value is not one of the accepted values. > > ```json theme={null} > { "error": "Invalid messageType. Must be email, sms, or imessage" } > ``` > > **Fix:** Use `"imessage"`, `"sms"`, or `"email"`. Or omit it entirely to > default to `"imessage"`. > [accordion] 400 — No active lines in workspace > > No `fromLineId` was provided and the workspace has no active lines to > round-robin from. > > ```json theme={null} > { "error": "No active lines in workspace..." } > ``` > > **Fix:** Provision at least one line in your workspace, or pass `fromLineId` > explicitly. > [accordion] 400 — Missing recipient > > No `recipientPhone`, `recipientEmail`, or `leadId` was provided, and the > resolved lead (if any) has no contact details. > > ```json theme={null} > { "error": "Either recipientEmail or recipientPhone is required..." } > ``` > > **Fix:** Send `recipientPhone` in E.164 (e.g. `"+12025551234"`) — that is how you address > a send. A `leadId` with a stored phone number works too. `recipientEmail` only reaches > someone over iMessage if that exact address is registered to their Apple account, so do not > reach for it as the default. > [accordion] 400 — Fallback not configured > > `sendFallbackSmsOnFailed` was set to `true` but the workspace doesn't have > Twilio fallback configured. > > ```json theme={null} > { "error": "...", "code": "FALLBACK_NOT_CONFIGURED" } > ``` > > **Fix:** Configure Twilio on your workspace via > `PATCH /api/workspace/fallback-config`, or set `sendFallbackSmsOnFailed` > to `false`. > [accordion] 401 — Unauthorized > > The API key is missing, invalid, or expired. > > ```json theme={null} > { "error": "Unauthorized" } > ``` > > **Fix:** Check your `Authorization: Bearer ` header. Generate a new > key from your workspace settings if needed. > [accordion] 402 — READ\_ONLY (subscription past due) > > The workspace subscription is past due and write operations are blocked. > > ```json theme={null} > { "error": "READ_ONLY", "code": "READ_ONLY", "reason": "past_due" } > ``` > > **Fix:** Update your billing in the Tuco dashboard. > [accordion] 404 — Lead not found > > A `leadId` was provided but no matching lead exists in the workspace. > > ```json theme={null} > { "error": "Lead not found or access denied" } > ``` > > **Fix:** Verify the `leadId` exists and belongs to the same workspace as > the API key. *** ## Status vs error — key distinction > [!WARNING] > > A `201` response with `status: "pending"` or `status: "scheduled"` is **not** > an error. It means the message was accepted and Tuco will send it when > conditions are met (time window, line limits, device gap, etc.). > > Only `4xx` and `5xx` responses indicate actual errors. | You received | What it means | Action | | - | - | - | | `201` + `"pending"` | Message accepted, sending soon | No action needed | | `201` + `"scheduled"` | Message accepted, will send at scheduled time | No action needed | | `201` + `"sent"` | Message sent immediately | No action needed | | `201` + `"fallback"` | Recipient has no iMessage, fallback may fire | Optional: send via another channel | | `400` | Validation error | Fix the request and retry | | `401` | Auth error | Check API key | | `402` | Billing issue | Update payment | | `404` | Resource not found | Check IDs | *** ## Rate limits Tuco applies per-workspace rate limits to protect the platform. When you hit a limit: * You receive a `429` response. * The `Retry-After` header tells you how many seconds to wait before retrying. * No data is modified — safe to retry. | Endpoint group | API rate limit | Daily cap | | - | - | - | | **Send message** (`/api/messages`) | 60 req/min | Per-line (see `GET /api/lines/by-user` for your limits) | | **Drip (bulk shock-absorber)** (`/api/drip`) | **Not rate-limited** (infra backstop only) | Per-line ban protector (paced automatically) | | **Check iMessage availability** (`/api/check-availability-rr`, `/api/leads/check-availability`) | 200 req/min | **70 checks/day per line** | | **Get replies** (`/api/replies`) | 120 req/min | — | | **Unibox reply** (`/api/unibox/send-reply`) | 30 req/min | — | | **Fallback SMS** (`/api/fallback-sms`) | 200 req/min | — | | **Invite teammate** (`/api/team/invite`) | — | **13 invites/day per workspace** (resets 00:00 UTC). See [Invite a Teammate](/api-reference/endpoint/team-invite#daily-limit) | All limits are per workspace (organization), regardless of how many API keys or users are calling the endpoint. > [!NOTE] > > **`POST /api/drip` is exempt from the 60/min send limit** and never returns `429` > for a normal blast — that is the whole point of the endpoint (a `429` would trigger > your CRM's retry storm and duplicate sends). It applies only a very high **infra > backstop** on the buffered intake (\~1,000 req/sec sustained / 10,000 burst per workspace) that > trips solely on runaway/abuse; if you ever hit it you get `429` + `Retry-After` and > can safely retry. Real send pacing (per line: 150 messages/day, 50 new contacts/day, new contacts ≤15/hr, > other messages ≤40/hr) is handled automatically at send time, not at intake. See > [Drip](/api-reference/drip). > [!NOTE] > > **Availability checks have two limits:** > > 1. **200 req/min** API rate limit (token bucket, per workspace) > 2. **70 checks/day per line** hard cap (each check hits a real device). With 3 lines = 210/day total. > > When the **daily cap** is exhausted (or no line is healthy), the check can't be completed, so > it returns `200` with `{ "available": false, "verified": false, "reason": "daily_quota_exhausted" }` > (or `"reason": "no_healthy_line"`) — **not** a `429`. This keeps CRM workflow steps from failing > on an un-checkable contact. Use `verified: false` to tell "couldn't check" apart from a confirmed > not-on-iMessage result (`available: false` with no `verified` flag). Only the **per-minute rate > limit** (#1 above) returns `429` with `Retry-After`. > > Availability checks do **not** consume your daily send quota — they use separate counters. > [!TIP] > > **For API integrators:** Skip availability checking entirely. Just call `POST /api/messages` > and listen for the `message.fallback` webhook to trigger your SMS/WhatsApp fallback. > This avoids burning your 70/day availability quota. See the > [check-availability-rr endpoint](/api-reference/endpoint/check-availability-rr#recommended-pattern-send--fallback-webhook) > for the recommended pattern. > [!TIP] > > For high-volume sends, use [`/api/drip`](/api-reference/drip) instead of individual > `/api/messages` calls. It paces sends per line automatically and is not subject to > per-request rate limits. # API Overview Source: https://docs.tuco.ai/api-reference/introduction How the Tuco AI API behaves from your point of view. Part of the Tuco AI iMessage API reference — bearer-token auth, JSON responses, examples in curl, Node. ## What the API Provides The Tuco AI API lets your own systems work directly with the same data you see in the Tuco dashboard. You can: * Create and update leads. * View and organize leads and lines. * Send messages through your approved sending identities. * Receive notifications when important events occur. The system automatically keeps behavior consistent between the API and the product UI, so the same actions feel familiar in both places. *** ## Access & Authentication API access is controlled from within your Tuco workspace. You decide: * Which workspaces may use the API. * Which environments may use production data. Once access is enabled, you receive credentials that allow your backend to act on behalf of your workspace. No action is required from you to keep these credentials recognized by Tuco; if they need to be changed or rotated, you handle that entirely from your own settings. *** ## Authorization with Tuco API Keys Tuco uses a workspace‑level API key for server‑side access. From your perspective: * Each key clearly belongs to a specific workspace. * You can enable or disable keys without affecting the rest of the product. * Requests made with a valid key are treated as coming from your workspace. You use the same Tuco key across all documented endpoints. For details on where to find this key and how it appears in the header, see `/api-reference/api-keys`. *** ## Request & Response Shape All endpoints follow a simple pattern: * A request either **succeeds** and confirms what was accepted. * Or it **fails** and clearly indicates why. You can rely on: * Standard HTTP status codes to understand whether a call worked. * Human‑readable messages that explain what went wrong when something is rejected. Data is preserved safely, so successful calls appear in the Tuco UI and can be used in reporting and audits. *** ## Correlation IDs (request tracing) Every request that hits a Tuco send endpoint can be tagged with a correlation ID. Pass it either as a header or as a field on the JSON body — whichever is easier from your client. If you don't pass one, Tuco generates a server-side ID prefixed `app_…` and threads it through the rest of the pipeline. | Where | Name | Example | | - | - | - | | Header (preferred) | `x-correlation-id` | `x-correlation-id: my-svc_2026-05-29_a73f9c` | | JSON body field | `correlationId` | `{ "correlationId": "my-svc_2026-05-29_a73f9c", … }` | The ID propagates into internal logs for that send — `message.api.request`, `message.api.create_message_returned`, `cap.reservation.entered/granted/denied`, `message.send.summary`. Grepping a single ID lets you reconstruct the whole request → gate → send → webhook chain. A few endpoints accept additional trace headers when integrating with a specific source system, so the same ID can stitch across multiple services: * `x-execution-id` — GHL workflow execution ID (forwarded by tuco-ghl). * `x-ghl-workflow-id` — GHL workflow definition ID. These are optional and only relevant when you are calling Tuco from another service that already has its own correlation context. *** ## Reliability & Limits The API is designed so that normal usage from typical business systems works without special tuning. If you reach a documented limit, you see clear error responses and nothing is changed unexpectedly. The system automatically handles internal protections to keep your account and recipients safe. For specific status codes and common outcomes, see `/api-reference/errors`. *** ## SDKs & Tools (Coming Soon) Official SDKs and helper libraries for popular languages are **Coming Soon**. They will focus on giving you a smoother developer experience without exposing any internal implementation details of Tuco AI. # Leads API Source: https://docs.tuco.ai/api-reference/leads How Tuco AI treats leads created, updated, and viewed through the API. Part of the Tuco AI iMessage API reference — bearer-token auth, JSON responses, examples. ## What the Leads API Does Leads created or updated through the API behave the same way as leads created in the Tuco dashboard. You can rely on the API to: * Add new people or accounts into Tuco, one at a time or in bulk. * Keep their core contact details aligned with your own systems. * Attach leads to the same lists and segments you see in the product. Whenever a request is accepted, the new or updated lead appears in the UI and can be used in sends and reporting with no extra setup. *** ## Typical Operations The Leads API is designed around a few predictable actions: * **Create or import leads** from your CRM or internal tools, either as single contacts or in large batches. * **Retrieve or search leads** so your systems can stay in sync — look up a contact by phone, email, name, or company, or fetch one by id. See [Get & Search Leads](/api-reference/endpoint/get). * **Update or remove leads** when details change or need to be cleared. * **Check messaging availability** for contact information where supported. The system automatically handles storing lead information in a way that remains stable over time, so your external IDs and Tuco IDs can be linked safely. *** ## Multiple Emails and Phone Numbers Tuco can store several emails and phone numbers for a single lead. From your perspective: * You can pass through the contact methods you already have for each person. * Tuco can use these to understand where messaging is possible. * API sends can be configured to focus on a primary contact method or take additional addresses into account. Data is preserved safely, so you can evolve how you use these fields over time without losing the original contact information. *** ## iMessage & Channel Availability Where enabled, Tuco can assess whether a lead is reachable over iMessage based on the contact details you provide. This gives you: * A clear signal about whether iMessage is available for a given lead. * The option to check availability for a single contact or for many at once. * The ability to use that signal in your own workflows, such as deciding whether to use iMessage, SMS, email, or another channel. The system automatically handles any internal checks; you only see the outcome and can design your flows accordingly. *** ## Personalization Inputs Tuco supports message templates that reference simple fields such as first name and other basic properties stored on the lead. From your point of view: * As long as the relevant fields are present on the lead, messages can use them for personalization. * Updates you make to lead data before a message is sent are reflected when that message is rendered. You do not need to manage any additional templating engine; the system automatically applies the latest lead data when sending. *** ## Data You Can Expect Lead‑related responses share a consistent shape. You can expect to see: * A unique identifier you can store in your own systems. * Core profile fields such as names and primary contact details. * `contactOwnerEmail` — the email of the workspace user assigned as contact owner. May be `null` for legacy leads or when no owner is explicitly set (defaults to the first workspace user). * Simple status indicators that match what you see in the Tuco UI. If a request is declined, Tuco clearly reports that no new lead was created or changed. *** ## When Something Goes Wrong If a Leads API call cannot be completed, you see a clear error message and status code. Your workspace data is not partially changed, and you remain in control of whether to correct the input, adjust your own logic, or contact support. For more about error meanings, see `/api-reference/errors`. *** ## Upload One or Many Contacts Both single and bulk uploads use the same endpoint. ### Endpoint * **Method**: `POST` * **Path**: `/api/leads` * **Auth**: Clerk (dashboard flows). For backend integrations, call this from a trusted server acting on behalf of a workspace. ### Request Body ```json theme={null} { "leads": [ { "firstName": "John", "lastName": "Doe", "email": "john@example.com", "phone": "+12025551234", "companyName": "Acme Corp", "jobTitle": "CEO", "notes": "Warm intro from Sarah", "contactOwnerEmail": "rep@yourcompany.com", "customFields": { "industry": "Technology", "segment": "Mid-market" } } ], "listId": "507f1f77bcf86cd799439011", "source": "api", "defaultCountryCode": "+1" } ``` * `leads` – one or more contacts; a single contact is just a one‑element array. * `listId` – Tuco list that should own these leads. * `source` – optional label for where the leads came from. * `defaultCountryCode` – used to normalize phone numbers when no country code is present. * `contactOwnerEmail` – Email of the workspace user who owns this contact. If omitted or invalid, defaults to the first user in the workspace. ### Response ```json theme={null} { "message": "Leads saved successfully", "savedCount": 1, "duplicateCount": 0, "totalProcessed": 1, "listId": "507f1f77bcf86cd799439011" } ``` Duplicates within the same list (based on email/phone) are skipped and reported via `duplicateCount`; they do not cause the call to fail. *** ## Check iMessage Availability for a Lead or Address Tuco exposes a dedicated API for checking iMessage reachability using the availability engine. ### Check a Specific Lead * **Method**: `GET` * **Path**: `/api/leads/check-availability?id={leadId}` * **Auth**: Tuco API key or Clerk (via `authenticateRequest`) ```bash theme={null} GET /api/leads/check-availability?id=667f1f77bcf86cd799439012 Authorization: Bearer tuco_xxx ``` **Response** ```json theme={null} { "success": true, "leadId": "667f1f77bcf86cd799439012", "available": true, "status": "available" } ``` `status` will be one of `available`, `unavailable`, or `error` and is also written back to the lead record. ### Check a Raw Phone or Email Address * **Method**: `POST` * **Path**: `/api/leads/check-availability` * **Auth**: Tuco API key or Clerk (via `authenticateRequest`) ```bash theme={null} POST /api/leads/check-availability Authorization: Bearer tuco_xxx Content-Type: application/json { "address": "+12025551234" } ``` **Response** ```json theme={null} { "success": true, "available": true, "address": "+12025551234" } ``` For batch lead availability (many leads at once), the same endpoint accepts `leadIds` or `listId` and may offload work to background processing; see `/features/check-availability` for behavioral details. # Lines API Source: https://docs.tuco.ai/api-reference/lines How Tuco AI exposes your sending identities through the API. Part of the Tuco AI iMessage API reference — bearer-token auth, JSON responses, examples in curl. ## Before You Request Lines The line-request API is for workspaces that already exist in Tuco. That means the normal first step is still: 1. Sign in to Tuco. 2. Create or join a workspace. 3. Buy a base plan for that workspace. 4. Use your workspace API key to request lines. If the workspace does not have an active subscription, Tuco returns `subscription_required` and does not create the request. *** ## What the Lines API Does Lines are the sending identities you use in Tuco, such as phone numbers and email addresses. Through the API, you can: * Request a new line. * Check whether a request is waiting for payment, provisioning, active, failed, or canceled. * Recover a payment link for a pending request. * Cancel a pending request you no longer want. * List the lines already attached to your workspace. * Update a line's name or profile photo. *** ## Line Request Flow The request flow is intentionally simple: 1. Submit the line details once. 2. Tuco checks your active plan and current capacity. 3. If the request is included in your plan, Tuco moves it straight to `provisioning`. 4. If the request requires an add-on, Tuco stores the line request as `awaiting_payment` and returns a hosted invoice link. 5. After payment succeeds, the request moves to `provisioning`. You do not need to resubmit the same line after payment. ### What happens if the user does not want to pay? If a line request is in `awaiting_payment`, the user can: * pay the invoice and let the same request continue * recover the payment link later * cancel the request entirely Canceling the pending request releases the payment block and lets the workspace create a different request. ### What happens if the user loses the payment link? Use the line-request management endpoint to recover it. If the invoice is still open, Tuco returns the same hosted invoice link. If billing has already been reconciled, the request may already move to `provisioning`. ### What blocks the next request? Only `awaiting_payment` blocks a new line request. A request already in `provisioning` does not block the next purchase. This lets a workspace continue buying or requesting lines while earlier ones are still being set up. *** ## Plan Behavior Tuco checks both the workspace plan and the line type you are requesting. | Plan | Phone lines | Email lines | | - | - | - | | Mini | Not available | First email included, more email lines paid | | Starter | First phone included, no extra phone lines | Paid add-ons | | Growth | First 2 phone lines included, more phone lines paid | Paid add-ons | Workspace-level overrides can still raise limits for specific customers. *** ## Line Request Statuses | Status | Meaning | | - | - | | `awaiting_payment` | The line request exists, but payment is still required before provisioning can begin | | `provisioning` | Tuco accepted the request and provisioning is underway | | `active` | The line is ready to use | | `failed` | Provisioning did not complete successfully | | `canceled` | The request was canceled before completion | *** ## Endpoints * [Create Line Request](/api-reference/endpoint/create-line-request) * [Get Line Request](/api-reference/endpoint/get-line-request) * [Manage Line Request](/api-reference/endpoint/manage-line-request) * [Get Lines](/api-reference/endpoint/get-lines) * [Update a Line](/api-reference/endpoint/update-line) ### Recommended integration pattern For most API clients, the cleanest pattern is: 1. Call `POST /api/line-requests` with the legal name, company name and `antiSpamAccepted: true` — plus, for a purchased phone line (eSIM), the legal address, `simCountry` (`US` or `CA`), the `zipcode` to provision on and `areaCodeBestEffortAcknowledged: true`. The display name is optional and falls back to the legal name. See [Create Line Request](/api-reference/endpoint/create-line-request). > [!NOTE] > > iMessage works globally. P2P SMS fallback from a line's own number only reaches recipients in the > country of that line's eSIM (`simCountry`). 2. If the response is `provisioning`, store the returned `line._id` 3. If the response is `awaiting_payment`, store the returned `line._id` and `paymentUrl` 4. Poll `GET /api/line-requests/{id}` until the status changes 5. If needed, call `POST /api/line-requests/{id}` with `action: "payment_link"` or `action: "cancel"` *** ## Fetch All Lines (API Key) ### Endpoint * **Method**: `GET` * **Path**: `/api/lines/by-user` * **Auth**: Tuco API key or Clerk token (via `authenticateRequest`) ### Behavior Returns all lines for the authenticated workspace, including: * current profile details * provisioning and payment state * per-day usage * public health information when available For request-specific lifecycle management, use the line-request endpoints above. `profileImageUrl` is the public URL of the line's profile photo, or `null` if none is set. It is part of the stable response. ### Example ```bash theme={null} GET /api/lines/by-user Authorization: Bearer tuco_xxx ``` ### Response ```json theme={null} { "lines": [ { "_id": "667f1f77bcf86cd799439011", "workspaceId": "org_123", "firstName": "Sales", "lastName": "Team 1", "profileImageUrl": "https://cdn.example.com/sales.png", "phone": "+12025551234", "email": "sales+1@example.com", "isActive": true, "provisioningStatus": "active", "paymentStatus": "paid", "requestSource": "api", "requestedChannelType": "email", "requestedLineType": "purchased", "paymentLinkUrl": null, "stripeInvoiceId": "in_123", "dailyNewConversationsLimit": 20, "dailyTotalMessagesLimit": 150, "usage": { "date": "2025-10-14", "newMessages": 3, "totalMessages": 42 }, "healthCheck": { "status": "healthy", "lastCheckedAt": "2025-10-14T10:00:00Z" } } ] } ``` *** ## Update a Line's Name, Photo or Call Recording Notice ### Endpoint * **Method**: `PATCH` * **Path**: `/api/lines/{id}` * **Auth**: Tuco API key Send any of `firstName`, `lastName`, `profileImageUrl` (use `null` to remove the photo), `callRecordingDisclosure` (`true` plays a "this call may be recorded" notice when the person you call answers) and `callRecordingDisclosureMessage` (your own wording, or `null` for the default). Other fields are rejected. See [Update a Line](/api-reference/endpoint/update-line). ```bash theme={null} PATCH /api/lines/667f1f77bcf86cd799439011 Authorization: Bearer tuco_xxx Content-Type: application/json { "firstName": "Sarah", "lastName": "Lee", "profileImageUrl": "https://cdn.example.com/sarah.png" } ``` *** ## Check Health of a Line ### Endpoint * **Method**: `GET` * **Path**: `/api/lines/check-availability?id={lineId}` * **Auth**: Clerk (Tuco dashboard or trusted backend using Clerk tokens) This endpoint performs a fresh health check for a specific line (server ping + iMessage availability) and updates the line’s health status. ### Example ```bash theme={null} GET /api/lines/check-availability?id=667f1f77bcf86cd799439011 Authorization: Bearer ``` ### Response (success) ```json theme={null} { "success": true, "lineId": "667f1f77bcf86cd799439011", "status": "healthy", "failures": [], "checkedAt": "2025-10-14T10:30:00Z", "shouldNotify": false, "notificationSent": false } ``` If the line is not active or lacks the necessary configuration, you receive a `400` with a descriptive error; on auth failure you receive `401`. # Message Webhooks Source: https://docs.tuco.ai/api-reference/message-webhooks Real-time webhooks for message sent, failure, fallback, reply, and AI-draft review events in the Tuco AI iMessage API. Bearer-token auth, JSON responses. ## Overview Message webhooks push status updates to a URL you control whenever a message reaches a terminal state. Configure them in your workspace settings — Tuco handles delivery automatically. > [!NOTE] > > Webhook calls are **POST** requests with a JSON body. All events share the same > base fields; each event type adds its own specific fields. **Outgoing message** > events are fired when a message is **sent** (accepted by Tuco), not when > delivery is confirmed on the recipient's device. > [!TIP] > > **Test before you go live.** [Send a test delivery](/api-reference/endpoint/send-test-webhook) for any event and variant — it is built by the same code as a live delivery, so if your parser handles the test it handles production. Every delivery (test or live) is in the [delivery log](/api-reference/endpoint/list-webhook-deliveries) with the exact body sent and your response, and any one can be [replayed](/api-reference/endpoint/replay-webhook-delivery). The same tools are in the dashboard under **Integrations → Webhooks**. *** ## Event types | Event | When | Payload `message` type | Status field | | - | - | - | - | | `message.sent` | Message was successfully sent (accepted by Tuco) | **Object** (full message doc) | `"sent"` | | `message.failed` | Message failed after all retries (technical error) | **Object** (full message doc) | `"failed"` | | `message.fallback` | Recipient has no iMessage; primary channel unavailable | **Object** (full message doc) | `"fallback"` | | `message.opened` | Recipient opened/read the message (read receipt; when supported) | **Object** (full message doc with `readAt`) | — | | `message.reply` | A lead or contact replied to a message you sent | **String** (reply text only) | — | | `message.reaction` | A lead reacted to one of your messages | **Object** (reaction event payload) | — | | `message.ai_draft` | AI copilot drafted a reply for review | **String** (draft text only) | — | | `message.ai_draft_approved` | Draft approved & sent (any channel: dashboard, Telegram, unibox, API) | **String** (draft text only) | — | | `message.ai_draft_rejected` | Draft rejected (any channel) | **String** (draft text only) | — | | `conversation.handover` | The AI SDR handed the conversation to a human and stopped replying | — (see `data.handover`) | — | | `call.recording.ready` | A call's recording is stored and downloadable (once per call) | — (see `data`) | — | | `dnc.added` | A contact was added to your Do-Not-Contact list — they replied STOP (iMessage or SMS), or you added them via the dashboard or `POST /api/dnc` (once per entry) | — (see `data.dnc`) | — | | `group.message.received` | Someone sent a message in an iMessage group your line is in | **Object** (full message doc) | `"delivered"` | | `group.message.sent` | Your message landed in a group | **Object** (full message doc) | `"sent"` | | `group.message.failed` | Your message to a group failed | **Object** (full message doc) | `"failed"` | | `group.message.reaction` | Someone in a group reacted (tapback) to a message | — (see `data`) | — | > [!NOTE] > > Group chats have their **own** events. A webhook on `message.*` never receives a group > message — tick the `group.message.*` events to get them. See [Group chat events](#group-chat-events). *** ## `message.ai_draft` — review AI drafts from your own tools When your knowledge base runs in **Copilot** mode, every AI-drafted reply fires `message.ai_draft` before anything is sent. The payload carries the draft text on `message` (string) and a `data.replyId` handle: ```json theme={null} { "event": "message.ai_draft", "timestamp": "2026-03-12T21:20:02.114Z", "workspaceId": "org_abc123", "leadId": "69b2c41d352a78479d2c623b", "lead": { "firstName": "Jane", "lastName": "Doe", "phone": "+15551230001" }, "message": "Sure — the onboarding call runs about 30 minutes. Thursday 2pm work?", "data": { "replyId": "69b330a1cad37b94a846ef01", "draftMessage": "Sure — the onboarding call runs about 30 minutes. Thursday 2pm work?", "conversationRecipient": "+15551230001", "inboundText": "How long is the onboarding call?", "confidence": 0.92, "mode": "copilot", "approveEndpoint": "/api/knowledge-base/auto-replies" } } ``` **Approve (sends the draft) or reject it** with your API key: ```bash theme={null} curl -X POST https://app.tuco.ai/api/knowledge-base/auto-replies \ -H "Authorization: Bearer tuco_YOUR_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "replyId": "69b330a1cad37b94a846ef01", "action": "approve" }' ``` `action` is `approve` (claims the draft **and** sends it), `reject`, or `mark_sent` (claim only — you already delivered the text yourself). The claim is atomic and first-action-wins across every channel, so an approval from Telegram, the dashboard, and your API call can never double-send. A `409` response means another channel already actioned the draft. Every resolution then fires `message.ai_draft_approved` or `message.ai_draft_rejected` — regardless of which channel actioned it — with `data.approvalChannel` (`dashboard`, `api`, `telegram`, `telegram_edit`, `telegram_retry`, `unibox_direct_send`) so your workflow can log who approved what, including approvals that never touched your tools. *** ## `message.reply` Sent when a new reply from a lead or contact is recorded. Use it to update your CRM, trigger automations, or log conversations. > [!NOTE] > > When a contact owner is set (`contactOwnerEmail`), reply email notifications are routed only to the contact owner rather than all workspace users. **Payload shape:** Top-level flat fields; **`data.reply`** is **identical** to one item in **GET /api/replies** (same keys, same types). Reply text is top-level **`message`** (string). **`parentMessages`** is always present (array; possibly empty). ### Top-level fields | Field | Description | | - | - | | `event` | `"message.reply"` | | `timestamp` | When the webhook was sent (ISO UTC) | | `workspaceId` | Workspace that owns the conversation | | `messageId` | ID of the **reply** message (the one they sent) | | `leadId` | Lead ID when the reply is linked to a lead. Omitted if no lead could be matched. | | `firstName` | Lead first name (when lead is present). Backward-compat flat field. | | `lastName` | Lead last name (when lead is present). Backward-compat flat field. | | `phone` | Lead phone (when lead is present). Backward-compat flat field. | | `listId` | Lead list ID (when lead is present). Backward-compat flat field. | | `fromLineId` | Line ID that received the reply. Backward-compat flat field. | | `recipientName` | Display name (lead name or recipient). Backward-compat flat field. | | `repliedAtUtc` | When the reply was received (UTC ISO 8601). **Always present.** | | `parentMessages` | Last 2 outbound messages you sent to this lead. **Always present** (array; empty if none). Same shape as GET /api/replies. | | `message` | **Reply text only** (string) — what they replied with. | | `attachmentDownloadUrls` | **Present only when the lead's reply included a photo/file.** Public, signed, 30-day URLs — `GET` each one (no auth header) to download the image/file bytes with the correct `Content-Type`. Omitted for text-only replies. | | `attachmentNames` | Filenames aligned 1:1 with `attachmentDownloadUrls` (e.g. `["IMG_1380.jpeg"]`). Omitted for text-only replies. | | `attachmentUrls` | Raw private-storage URLs for reference. These return `403` on their own — use `attachmentDownloadUrls` to fetch the bytes. | | `originalMessageId` | ID of the message they replied to (when known) | | `originalMessage` | Original outbound message object (when known) | | `lead` | Full lead object when available. Omitted if no lead could be matched. | ### `message` (reply text only) For `message.reply`, **`message`** is the **reply text only** (string) — what the lead or contact replied with. ### `data.reply` — matches GET /api/replies item exactly **`data.reply`** has the **exact same shape** as one element of **GET /api/replies** `replies` array: | Field | Description | | - | - | | `leadId` | Lead ID (string) | | `messageId` | Reply message ID | | `respondedAtUtc` | When the reply was received (UTC ISO) | | `recipientEmail` | Recipient email or undefined | | `recipientPhone` | Recipient phone or undefined | | `name` | Display name (lead name or recipient) | | `attachmentDownloadUrls` | Signed, fetchable download URLs for the latest reply's attachments (only when it had any). | | `attachmentNames` | Filenames aligned 1:1 with `attachmentDownloadUrls`. | | `parentMessages` | Array of `{ messageId, message, sentAtUtc, batchId, stepIndex }` (same as API) | | `recentReplies` | Array of `{ messageId, message, receivedAtUtc, attachmentDownloadUrls?, attachmentNames? }` — last 10 inbound replies (same as API) | Plus `recentReplies` — the last 10 inbound replies from this lead (array, possibly empty): | Field | Description | | - | - | | `messageId` | Reply message ID | | `message` | Reply text | | `receivedAtUtc` | When the reply was received (UTC ISO) | | `attachmentDownloadUrls` | Signed, fetchable download URLs — present only on replies that carried attachments. | | `attachmentNames` | Filenames aligned 1:1 with `attachmentDownloadUrls`. | Example payload: ```json theme={null} { "event": "message.reply", "timestamp": "2025-03-02T15:00:00.000Z", "workspaceId": "org_xxx", "messageId": "674abc...", "leadId": "667f1f77bcf86cd799439012", "firstName": "Jane", "lastName": "Doe", "phone": "+12025551234", "listId": "674list...", "fromLineId": "699f704bc405fae6ca299a08", "recipientName": "Jane Doe", "repliedAtUtc": "2025-03-02T14:59:58.000Z", "parentMessages": [ { "messageId": "674def...", "message": "Hi Jane, we have an offer...", "sentAtUtc": "2025-03-01T10:00:00.000Z", "batchId": null, "stepIndex": null } ], "message": "Thanks, I'm interested!", "data": { "reply": { "leadId": "667f1f77bcf86cd799439012", "messageId": "674abc...", "respondedAtUtc": "2025-03-02T14:59:58.000Z", "recipientEmail": "jane@example.com", "recipientPhone": null, "name": "Jane Doe", "parentMessages": [ { "messageId": "674def...", "message": "Hi Jane, we have an offer...", "sentAtUtc": "2025-03-01T10:00:00.000Z", "batchId": null, "stepIndex": null } ], "recentReplies": [ { "messageId": "674abc...", "message": "Thanks, I'm interested!", "receivedAtUtc": "2025-03-02T14:59:58.000Z" } ] }, "repliedAtUtc": "2025-03-02T14:59:58.000Z", "parentMessages": [ { "messageId": "674def...", "message": "Hi Jane, we have an offer...", "sentAtUtc": "2025-03-01T10:00:00.000Z", "batchId": null, "stepIndex": null } ] }, "originalMessageId": "674def...", "lead": { "firstName": "Jane", "lastName": "Doe", "email": "jane@example.com" } } ``` ### Reply with a photo/file When the lead replies with an image or file, the same payload additionally carries `attachmentDownloadUrls` + `attachmentNames` (top-level **and** inside `data.reply` / its `recentReplies`). `GET` a download URL to store the bytes — no `Authorization` header needed, the signature is the capability: ```json theme={null} { "event": "message.reply", "workspaceId": "org_xxx", "messageId": "674abc...", "message": "here's the damage on my car", "attachmentDownloadUrls": [ "https://app.tuco.ai/api/attachments/crm-media/IMG_1380.jpeg?u=aHR0cHM...&exp=1786752000000&sig=Vh9k..." ], "attachmentNames": ["IMG_1380.jpeg"], "attachmentUrls": ["https://abc.private.blob.vercel-storage.com/workspaces/org_xxx/attachments/2996...-IMG_1380.jpeg"], "data": { "reply": { "leadId": "667f1f77bcf86cd799439012", "messageId": "674abc...", "respondedAtUtc": "2025-03-02T14:59:58.000Z", "attachmentDownloadUrls": ["https://app.tuco.ai/api/attachments/crm-media/IMG_1380.jpeg?u=...&exp=...&sig=..."], "attachmentNames": ["IMG_1380.jpeg"], "recentReplies": [ { "messageId": "674abc...", "message": "here's the damage on my car", "receivedAtUtc": "2025-03-02T14:59:58.000Z", "attachmentDownloadUrls": ["https://app.tuco.ai/api/attachments/crm-media/IMG_1380.jpeg?u=...&exp=...&sig=..."], "attachmentNames": ["IMG_1380.jpeg"] } ] } } } ``` > [!NOTE] > > **Multiple attachments per reply.** A single reply can carry many photos/files — > `attachmentDownloadUrls` and `attachmentNames` are parallel arrays with one entry per > attachment (there is no longer a 2-attachment cap; the full set is captured). > > **Large bursts arrive progressively.** When a lead sends a big batch (e.g. 20 photos), the > first few are attached to the `message.reply` webhook right away and the rest are ingested > in the background — the underlying iMessage server hands each attachment over slowly, so a > large burst takes a couple of minutes to finish. The webhook is **not** re-sent as the > remainder land, so to get the **complete** set for a `messageId`, call > [`GET /api/replies`](/api-reference/endpoint/get-replies) a minute or two after the reply. > [!WARNING] > > Each `attachmentDownloadUrls` link is a signed, 30-day capability to read that one file. Fetch and store the bytes in your own system rather than persisting the URL. Need a fresh link later? Call [`GET /api/replies`](/api-reference/endpoint/get-replies) or wait for the next `message.reply`. *** ## `message.sent` Sent when a message has been **sent** (accepted by Tuco). This is the only outgoing-message event fired to your webhook; Tuco does not fire a separate event when delivery is confirmed on the recipient's device. **Payload:** The **`message`** field is the **full message object** (not a string), with `_id`, `message`, `messageType`, `status`, `fromLineId`, `recipientPhone`, `recipientEmail`, `recipientName`, `leadId`, `workspaceId`, `createdByUserId`, `sentAt`, `createdAt`, `updatedAt`, etc. Top-level also includes `leadId`, `lead` (full lead when available), and integration IDs. ### Full example body ```json theme={null} { "event": "message.sent", "timestamp": "2026-03-12T22:57:03.000Z", "workspaceId": "org_3AZs4H8UsfFxVFONr6H4K75okaG", "messageId": "69b344bc6dae1d942ece4d0e", "message": { "_id": "69b344bc6dae1d942ece4d0e", "message": "Here's your document.", "messageType": "imessage", "status": "sent", "fromLineId": "69ab427ac1feb77d7f46462e", "recipientPhone": "+919876543210", "recipientEmail": "jane@example.com", "recipientName": "Jane Doe", "leadId": "69b2c41d352a78479d2c623b", "workspaceId": "org_3AZs4H8UsfFxVFONr6H4K75okaG", "createdByUserId": "user_3AZrxEi8CR2uMq9simYrwcJpfsL", "sentAt": "2026-03-12T22:57:02.892Z", "createdAt": "2026-03-12T22:57:00.856Z", "updatedAt": "2026-03-12T22:57:02.892Z" }, "leadId": "69b2c41d352a78479d2c623b", "lead": { "_id": "69b2c41d352a78479d2c623b", "firstName": "Jane", "lastName": "Real", "email": "jane@example.com", "phone": "+919876543210", "listId": "69ab444ac1feb77d7f46462f", "workspaceId": "org_3AZs4H8UsfFxVFONr6H4K75okaG", "source": "gohighlevel" }, "ghlContactId": "aMUQn0u0Z7cw0NQ7tJ5R", "ghlLocationId": "eL7DD22BdZ0rismu7qCA", "hsPortalId": null, "hsContactId": null, "channel": "imessage", "data": {} } ``` **event** `string` `"message.sent"` **channel** `string` How the message actually left: `imessage`, `p2p_sms`, `email`, or `call`. See [P2P SMS](#p2p-sms-green-bubble-from-your-line). **messageId** `string` Tuco message ID **message** `object` Full message document (not string) **leadId** `string` Lead ID when known **lead** `object` Full lead when available **ghlContactId** `string | null` GHL contact ID for integrations **ghlLocationId** `string | null` GHL location ID for integrations **timestamp** `string` When the webhook was fired (ISO UTC) `message.sent` fires **exactly once per message**, whichever way the send was confirmed. ### P2P SMS (green bubble from your line) When a line has P2P SMS on and the recipient isn't on iMessage, the line's paired iPhone sends a regular SMS **from the line's own number**. That is a successful send by your line, so you get **`message.sent` with `"channel": "p2p_sms"`**, and **no** `message.fallback`. The message object keeps `messageType: "imessage"` (what was requested) and carries `smsForwarded: true`, so read `channel` rather than `messageType` to know how it actually went out. Abbreviated: only the fields that differ from the full example above are shown. ```json theme={null} { "event": "message.sent", "messageId": "69b344bc6dae1d942ece4d0e", "message": { "_id": "69b344bc6dae1d942ece4d0e", "messageType": "imessage", "status": "sent", "smsForwarded": true, "smsForwardedMethod": "apple-script" }, "channel": "p2p_sms" } ``` > [!NOTE] > > P2P SMS is different from **fallback**. Fallback (`message.fallback`) means the message went out > through your workspace's fallback provider (Twilio, GoHighLevel, or your own fallback webhook) from > a different number. A message never produces both. *** ## `message.reaction` Sent when a lead or contact reacts to an existing message in a conversation. Tuco treats reactions differently from replies: * they are stored as reactions on the original message * they do not become a normal text reply * they do not trigger AI reply handling ### Top-level fields | Field | Description | | - | - | | `event` | `"message.reaction"` | | `timestamp` | When the webhook was sent (ISO UTC) | | `workspaceId` | Workspace that owns the conversation | | `messageId` | The original message id that received the reaction, when Tuco can match it | | `leadId` | Lead id when the conversation is linked to a lead | | `firstName` | Lead first name when available | | `lastName` | Lead last name when available | | `phone` | Lead phone when available | | `fromLineId` | The line that received the reaction | | `recipientName` | Lead or contact display name | | `message` | The raw reaction text emitted by the upstream channel | | `data.reaction` | Normalized reaction type such as `love`, `like`, `dislike`, `laugh`, `emphasize`, or `question` | | `data.reactedAtUtc` | When Tuco recorded the reaction | | `data.reactionMessageId` | Upstream reaction message id when available | ### Example payload ```json theme={null} { "event": "message.reaction", "timestamp": "2026-05-18T16:30:00.000Z", "workspaceId": "org_xxx", "messageId": "6a07878bafb1789f8fcb68e6", "leadId": "667f1f77bcf86cd799439012", "firstName": "Jane", "lastName": "Doe", "phone": "+12025551234", "fromLineId": "699f704bc405fae6ca299a08", "recipientName": "Jane Doe", "message": "Loved “Looks good to me”", "data": { "reaction": "love", "reactedAtUtc": "2026-05-18T16:29:58.000Z", "reactionMessageId": "BB-123" } } ``` *** ## `message.failed` Sent **once** when a message definitely did **not** go out: | Case | `message.errorMessage` | | - | - | | The message waited for a line that was down longer than the queue window (24 hours) and expired | `Line unavailable for longer than the 24h queue window — message not sent` | | Sending failed twice in a row with an error from the device | the error, e.g. `Request failed with status code 502` | `message.failed` is **not** sent when delivery simply could not be confirmed (the message may still have arrived — check the conversation), or when Tuco declines to send a message (for example a link or attachment in the very first message to a new contact). The **`message`** field is the full message object, including `errorMessage`, `failureReason` (`line_down_expired` or `transient_exhausted`) and `failureClass`. **`data.error`** repeats the reason. ### Full example body ```json theme={null} { "event": "message.failed", "timestamp": "2026-10-15T22:40:43.117Z", "workspaceId": "org_xxx", "leadId": "7e57ab1e0000000000000001", "messageId": "7e57ab1e0000000000000002", "message": { "_id": "7e57ab1e0000000000000002", "message": "This is a test webhook from Tuco. If you see this, your endpoint is working correctly.", "messageType": "imessage", "direction": "sent", "recipientPhone": "+15551234567", "recipientName": "Test Contact", "fromLineId": "7e57ab1e0000000000000003", "fromLinePhone": "+15557654321", "fromLineEmail": "line@example.com", "leadId": "7e57ab1e0000000000000001", "source": "api", "workspaceId": "org_xxx", "createdByUserId": "user_test", "status": "failed", "externalMessageId": "TEST-0000-0000-0000-000000000001", "createdAt": "2026-10-15T22:40:43.116Z", "updatedAt": "2026-10-15T22:40:43.116Z", "errorMessage": "Line unavailable for longer than the 24h queue window \u2014 message not sent", "failureReason": "line_down_expired", "failureClass": "permanent" }, "contactOwnerEmail": null, "ghlContactId": null, "ghlLocationId": null, "hsPortalId": null, "hsContactId": null, "data": { "error": "Line unavailable for longer than the 24h queue window \u2014 message not sent" } } ``` **event** `string` `"message.failed"` **message** `object` Full message document (includes errorMessage) **data.error** `string` Human-readable explanation of the failure > [!NOTE] > > Tuco does not send an SMS because of `message.failed`. To retry another way, do it from your > workflow when this event arrives. (Recipients without iMessage are a different case: > see [`message.fallback`](#message-fallback).) *** ## `message.fallback` Sent when Tuco determines that the primary channel (e.g. iMessage) is not available for this recipient. This is a **business outcome**, not a technical failure. The **`message`** field is the **full message object**. **`data`** includes `reason` and optionally `checkedAddresses` (string\[]). ### Full example body ```json theme={null} { "event": "message.fallback", "timestamp": "2026-03-12T22:42:23.000Z", "workspaceId": "org_xxx", "messageId": "69b3414e6dae1d942ece4d0d", "message": { "_id": "69b3414e6dae1d942ece4d0d", "message": "Hi from N8N - mar 13", "messageType": "imessage", "status": "fallback", "recipientPhone": "+919876543211", "recipientName": "Usha Giridhar", "leadId": "69b3414e6dae1d942ece4d0c", "workspaceId": "org_xxx", "errorMessage": "Prospect's iMessage not available on +919876543211", "createdAt": "2026-03-12T22:42:22.379Z", "updatedAt": "2026-03-12T22:42:22.962Z" }, "leadId": "69b3414e6dae1d942ece4d0c", "lead": { "_id": "69b3414e6dae1d942ece4d0c", "firstName": "Usha", "lastName": "Giridhar", "phone": "+919876543211" }, "ghlContactId": "8LUvKi8KL6oPnjHuUeAG", "ghlLocationId": "eL7DD22BdZ0rismu7qCA", "hsPortalId": null, "hsContactId": null, "data": { "reason": "Prospect's iMessage not available on +919876543211", "checkedAddresses": ["+919876543211"] } } ``` **event** `string` `"message.fallback"` **message** `object` Full message document (status fallback) **data.reason** `string` Human-readable explanation **data.checkedAddresses** `string[]` All addresses Tuco checked for iMessage availability before deciding fallback. Useful for debugging and auditing. ### Common patterns > [card] Auto-send SMS > > Trigger an SMS via your own Twilio/fallback when you receive `message.fallback`. > Or enable Tuco's built-in fallback SMS on the workspace. > [card] Tag lead in CRM > > Flag the lead as "no iMessage" so future sends pick the right channel > automatically. *** ## `message.opened` Sent when the recipient has **opened/read** the message (read receipt). Fired where the channel supports read receipts. Use it to track engagement or trigger follow-ups. **Payload:** Same top-level shape as `message.sent`. The **`message`** field is the **full message object** (not a string), including **`readAt`** (ISO 8601 UTC) when the message was read. **`data`** may include `readAt`. ### Full example body ```json theme={null} { "event": "message.opened", "timestamp": "2026-03-13T10:00:00.000Z", "workspaceId": "org_xxx", "messageId": "69b344bc6dae1d942ece4d0e", "message": { "_id": "69b344bc6dae1d942ece4d0e", "message": "Here's your document.", "messageType": "imessage", "status": "sent", "fromLineId": "69ab427ac1feb77d7f46462e", "recipientPhone": "+919876543210", "recipientEmail": "jane@example.com", "recipientName": "Jane Doe", "leadId": "69b2c41d352a78479d2c623b", "workspaceId": "org_xxx", "createdByUserId": "user_xxx", "sentAt": "2026-03-12T22:57:02.892Z", "readAt": "2026-03-13T10:00:00.000Z", "createdAt": "2026-03-12T22:57:00.856Z", "updatedAt": "2026-03-13T10:00:00.000Z" }, "leadId": "69b2c41d352a78479d2c623b", "lead": { "_id": "69b2c41d352a78479d2c623b", "firstName": "Jane", "lastName": "Real", "email": "jane@example.com", "phone": "+919876543210" }, "ghlContactId": "aMUQn0u0Z7cw0NQ7tJ5R", "ghlLocationId": "eL7DD22BdZ0rismu7qCA", "hsPortalId": null, "hsContactId": null, "data": { "readAt": "2026-03-13T10:00:00.000Z" } } ``` **event** `string` `"message.opened"` **message** `object` Full message document including **readAt** (ISO UTC when read) **data.readAt** `string` When the message was opened (ISO UTC) *** ## `conversation.handover` Fires **once** when the AI SDR decides a conversation needs a person and stops replying to it. This is the event to wire to your routing, your inbox or your on-call rota — it is the only signal that a lead is waiting on a human. > [!NOTE] > > The AI is already paused when this fires (`data.handover.aiPaused` is always `true`). Nothing > further is sent on that conversation until a person takes it. **Payload shape** ```json theme={null} { "event": "conversation.handover", "timestamp": "2026-10-06T09:14:02.118Z", "workspaceId": "org_3AZs4H8UsfFxVFONr6H4K75okaG", "leadId": "69b2c41d352a78479d2c623b", "contactOwnerEmail": "rep@yourcompany.com", "data": { "handover": { "recipient": "+13025550123", "trigger": "pricing_question", "reason": "Lead asked for custom enterprise pricing, which the bot may not quote.", "confidence": 0.92, "inboundText": "what would this cost for 40 seats?", "withheldDraft": "Great question — let me get you exact numbers.", "contactOwnerEmail": "rep@yourcompany.com", "handedOverAt": "2026-10-06T09:14:02.090Z", "aiPaused": true } } } ``` ### `data.handover` **recipient** `string` The contact the conversation is with — phone in E.164, or email. **trigger** `string` What tripped the handover, e.g. a rule name or detected intent. **reason** `string` Plain-English explanation of why the bot stopped. Safe to show a rep. **confidence** `number` Model confidence in the handover decision, `0`–`1`. Omitted when not scored. **inboundText** `string` The lead's message that triggered it. Omitted when there is none. **withheldDraft** `string` **What the AI would have said, held back.** Hand this to whoever picks the conversation up so the lead does not have to repeat themselves. Omitted when there was no draft. **contactOwnerEmail** `string` Owner of the contact, for routing. Also present at the top level. **handedOverAt** `string` ISO 8601 timestamp of the handover. **aiPaused** `boolean` Always `true`. The AI has stopped replying to this conversation. > [!NOTE] > > `leadId` and `contactOwnerEmail` are also lifted to the **top level** so you can route on owner > without reaching into `data.handover`. They are omitted when unknown. *** ## Group chat events For iMessage **group chats** your line is in. A group is not a lead, so these events have no `leadId`, `lead` or CRM ids. Instead every group event carries a top-level `group` object. | Event | Fires when | | - | - | | `group.message.received` | A member sends a message (text, photo, file) in the group | | `group.message.sent` | Your message (text, file or voice note) lands in the group | | `group.message.failed` | Your message to the group fails | | `group.message.reaction` | A member reacts (tapback) to a message in the group | Each fires **once per message** (once per tapback for reactions), like the 1:1 events. ### The `group` object | Field | Description | | - | - | | `group.conversationId` | The group's id. Send to it with [Send to a Group Chat](/api-reference/endpoint/send-group-message); read it with [List Conversations](/api-reference/endpoint/conversations#group-chats) | | `group.chatGuid` | The iMessage group id | | `group.name` | The group's name, when someone set one. Otherwise `null` | | `group.members` | Every member: `{ "address", "name" }`. `name` is there when the member is one of your leads | | `group.sender` | Who did it — the member who sent or reacted. `null` on `sent` and `failed` (that was you) | ### `group.message.received` `message` is the full message doc. `message.groupSenderAddress` is the sender too. Photos and files are in `attachmentUrls` and, fetchable with no auth, `attachmentDownloadUrls`. ```json theme={null} { "event": "group.message.received", "timestamp": "2026-11-06T17:13:00.650Z", "workspaceId": "org_xxx", "messageId": "6aedeb65fa7ac0d2e5e221d5", "message": { "_id": "6aedeb65fa7ac0d2e5e221d5", "message": "Sounds good, see you at 3", "messageType": "imessage", "direction": "received", "isGroupChat": true, "groupChatGuid": "iMessage;+;chat606535035660201399", "groupSenderAddress": "+13025550100", "status": "delivered", "fromLineId": "699f704bc405fae6ca299a08", "externalMessageId": "7A76BED5-557B-431D-996B-E2343159C533", "attachmentUrls": [], "sentAt": "2026-11-06T17:12:58.000Z" }, "fromLineId": "699f704bc405fae6ca299a08", "channel": "imessage", "data": { "voiceNote": false }, "group": { "conversationId": "group:iMessage;+;chat606535035660201399", "chatGuid": "iMessage;+;chat606535035660201399", "name": null, "members": [ { "address": "+13025550100", "name": "Alex Smith" }, { "address": "sam@example.com" } ], "sender": { "address": "+13025550100", "name": "Alex Smith" } } } ``` ### `group.message.sent` Same shape, with `direction: "sent"`, `status: "sent"` and `group.sender: null`. `data.voiceNote` is `true` for a voice note. * A text or file send fires when **every part** of it is in the group. * A voice note fires when it lands (a few seconds after the API answers). * A message typed on the phone itself does **not** fire (same as 1:1). ### `group.message.failed` Same shape, with `status: "failed"` and the reason in `data.error`: ```json theme={null} { "event": "group.message.failed", "messageId": "6aedeb65fa7ac0d2e5e221d5", "data": { "error": "fetch failed (ECONNRESET)" }, "group": { "conversationId": "group:iMessage;+;chat606535035660201399", "sender": null } } ``` > [!WARNING] > > A send that timed out can still land. Tuco then fires `group.message.sent` for the > **same** `messageId`. Treat `sent` as the final word. ### `group.message.reaction` `messageId` is the message that was reacted to. `group.sender` is who reacted. Your own reactions do not fire (same as 1:1). | Field | Description | | - | - | | `data.reaction` | `love`, `like`, `dislike`, `laugh`, `emphasize`, `question` or `emoji` | | `data.emoji` | The emoji, when `data.reaction` is `emoji` | | `data.removed` | `true` when the member took the reaction back | | `data.reactedAtUtc` | When they reacted | | `data.reactionMessageId` | The tapback's own id. Use it to dedupe | ```json theme={null} { "event": "group.message.reaction", "timestamp": "2026-11-06T17:13:00.650Z", "workspaceId": "org_xxx", "messageId": "6aedeb65fa7ac0d2e5e221d5", "fromLineId": "699f704bc405fae6ca299a08", "channel": "imessage", "data": { "reaction": "love", "removed": false, "reactedAtUtc": "2026-11-06T17:13:00.650Z", "direction": "received", "reactionMessageId": "E530C2E6-0000-0000-0000-000000000000" }, "group": { "conversationId": "group:iMessage;+;chat606535035660201399", "chatGuid": "iMessage;+;chat606535035660201399", "name": null, "members": [ { "address": "+13025550100", "name": "Alex Smith" }, { "address": "sam@example.com" } ], "sender": { "address": "+13025550100", "name": "Alex Smith" } } } ``` *** ## Shared fields (all events) Every webhook payload includes these base fields: | Field | Description | | - | - | | `event` | Event type: `message.sent`, `message.failed`, `message.fallback`, `message.opened`, or `message.reply` | | `timestamp` | When the webhook was sent (ISO UTC) | | `workspaceId` | Your workspace ID | | `messageId` | Tuco message ID — use as your primary key (for reply, this is the **reply** message ID) | | `message` | **For sent/failed/fallback/opened:** full message object. **For reply:** string (reply text only) | | `leadId` | Lead involved (when known) | | `lead` | Full lead object when available | | `contactOwnerEmail` | Email of the workspace user assigned as contact owner for this lead. May be `null` for legacy leads. | | `ghlContactId`, `ghlLocationId`, `hsPortalId`, `hsContactId` | Integration IDs (nullable) | | `data` | Event-specific data (e.g. `reason`, `checkedAddresses` for fallback; `reply`, `repliedAtUtc`, `parentMessages` for reply; `readAt` for opened) | *** ## `call.recording.ready` Sent **once per call**, when the call's recording has been stored. Use `data.recordingDownloadUrl` to fetch the audio: it is a signed, public link valid for 30 days and needs no Authorization header. `data.recordingUrl` is the raw storage location and is not fetchable with an API key. ### Full example body ```json theme={null} { "event": "call.recording.ready", "timestamp": "2026-10-15T21:39:55.737Z", "workspaceId": "org_xxx", "leadId": "7e57ab1e0000000000000001", "lead": { "_id": "7e57ab1e0000000000000001", "firstName": "Test", "lastName": "Contact", "email": "test.contact@example.com", "phone": "+15551234567", "companyName": "Test Co", "listId": "7e57ab1e0000000000000004", "workspaceId": "org_xxx", "source": "api", "createdAt": "2026-01-01T00:00:00.000Z", "updatedAt": "2026-01-01T00:00:00.000Z" }, "contactOwnerEmail": null, "ghlContactId": null, "ghlLocationId": null, "hsPortalId": null, "hsContactId": null, "data": { "ghlContactId": null, "ghlLocationId": null, "hsPortalId": null, "hsContactId": null, "callId": "7e57ab1e0000000000000007", "lineId": "7e57ab1e0000000000000003", "surface": "unibox", "from": "+15557654321", "to": "+15551234567", "callStatus": "billed", "requestedAt": "2026-10-15T21:39:55.736Z", "answeredAt": "2026-10-15T21:39:55.736Z", "endedAt": "2026-10-15T21:39:55.736Z", "durationSec": 42, "hangupCause": "normal_clearing", "recordingUrl": "https://example.private.blob.vercel-storage.com/tuco-test/recordings/call.mp3", "recordingDownloadUrl": "https://app.tuco.ai/api/attachments/crm-media/call.mp3?u=aHR0cHM6Ly9leGFtcGxlLnByaXZhdGUuYmxvYi52ZXJjZWwtc3RvcmFnZS5jb20vdHVjby10ZXN0L3JlY29yZGluZ3MvY2FsbC5tcDM&exp=1794692395737&sig=yvnwFVMl3XL2jNcmtg7iNtC5XkYuvBesCggEQMzjAr8", "recordingName": "call.mp3" } } ``` **data.callId** `string` Tuco call id. **data.from** `string` Number the call was placed from (your line), E.164. **data.to** `string` Number that was called, E.164. **data.durationSec** `number | null` Talk time in seconds. **data.callStatus** `string | null` Call status when the recording was stored, e.g. `billed`. **data.recordingDownloadUrl** `string` Signed link that streams the audio (30 days). **data.recordingName** `string` File name, e.g. `call.mp3`. *** ## `dnc.added` Sent **once per new Do-Not-Contact entry**. Use it to stop the same person on your other channels (WhatsApp, email, dialer) the moment they opt out of iMessage. It fires when: * a contact replies with an opt-out keyword (`STOP`, `UNSUBSCRIBE`, `OPT OUT`, `REMOVE ME`, `DO NOT CONTACT`) on iMessage, or a carrier keyword (`STOP`, `STOPALL`, `UNSUBSCRIBE`, `CANCEL`, `END`, `QUIT`) to your Telnyx or Twilio fallback number * someone adds a contact in the dashboard, or you call `POST /api/dnc` A second `STOP` from someone already on the list does not fire again. Bulk CSV and list imports, and DNC mirrored in from GoHighLevel or HubSpot, do not fire — read those with [`GET /api/dnc?since=`](/features/dnc#poll-for-new-opt-outs). The reply itself still arrives as `message.reply` with `optedOut: true`. Try it without waiting for a real opt-out: ```bash theme={null} curl -X POST "https://app.tuco.ai/api/webhooks//test" \ -H "Authorization: Bearer tuco_xxxxxxxxxxxxx" \ -H "Content-Type: application/json" \ -d '{ "event": "dnc.added", "variant": "opt_out" }' ``` Variants: `opt_out` (replied STOP) and `manual` (added via the dashboard or API). ### Full example body ```json theme={null} { "event": "dnc.added", "timestamp": "2026-10-19T11:22:49.694Z", "workspaceId": "org_xxx", "leadId": "7e57ab1e0000000000000001", "contactOwnerEmail": null, "ghlContactId": null, "ghlLocationId": null, "hsPortalId": null, "hsContactId": null, "optedOut": true, "data": { "ghlContactId": null, "ghlLocationId": null, "hsPortalId": null, "hsContactId": null, "optedOut": true, "dnc": { "id": "7e57ab1e0000000000000008", "phone": "+15551234567", "email": null, "reason": "opt-out", "source": "keyword-STOP", "addedBy": "system", "addedAt": "2026-10-19T11:22:49.693Z", "keyword": "stop" } } } ``` **data.dnc.id** `string` DNC entry id. Same id `GET /api/dnc` returns, so you can dedupe across the webhook and polling. **data.dnc.phone** `string | null` Phone number, E.164. **data.dnc.email** `string | null` Email address, lower case. **data.dnc.reason** `string` `opt-out` for a reply, otherwise the reason given when it was added (default `manual`). **data.dnc.source** `string` `keyword-` for a reply (e.g. `keyword-STOP`), `api` for `POST /api/dnc` with an API key, `manual-ui` for the dashboard. **data.dnc.keyword** `string` The opt-out text they sent. Only present for replies. **data.dnc.addedAt** `string` When the entry was added (ISO 8601, UTC). *** ## Headers & signature verification Every webhook POST includes these headers: | Header | Description | | - | - | | `Content-Type` | `application/json` | | `X-Tuco-Signature` | HMAC-SHA256 hex digest of the JSON body, signed with your webhook secret | | `X-Tuco-Event` | Event type (e.g. `message.sent`) | | `X-Tuco-Timestamp` | ISO 8601 UTC timestamp of when the webhook was fired | | `X-Tuco-Event-Id` | Stable id of the logical event (`evt_…`). The same on a retry and on a [replay](/api-reference/endpoint/replay-webhook-delivery). | | `X-Tuco-Delivery-Id` | Id of this delivery to this endpoint (`dlv_…`). The same on Tuco's automatic retry; new on a replay. | | `X-Tuco-Replay` | `true` when the delivery was re-sent with the Replay endpoint or button. | | `X-Tuco-Test` | `true` when sent by the [test endpoint](/api-reference/endpoint/send-test-webhook). The body also carries `"testMode": true`. | | `Authorization` | Only when you configured a custom Authorization header on the webhook; sent verbatim. | ### Delivery guarantees * Each event fires **once per webhook**. `message.sent` fires once per message, whichever way the send was confirmed; `message.reply` once per inbound message; `message.failed`, `message.fallback`, `message.opened`, `message.reaction` and the `message.ai_draft*` events once per message, reaction or draft. * If your endpoint does not answer `2xx` within 10 seconds, Tuco retries **once** after 5 seconds with the **same** `X-Tuco-Delivery-Id`. If your endpoint already processed the first attempt (it was just slow), drop the retry by that id. * Every delivery is kept for 30 days in the [delivery log](/api-reference/endpoint/list-webhook-deliveries), with the exact body sent and your endpoint's response. > [!TIP] > > Verify the signature against the **raw request body** exactly as received. Re-serializing a parsed body can change it and make a valid signature fail. **Verify signatures** to confirm webhooks actually came from Tuco: ```javascript Node.js theme={null} const crypto = require('crypto'); function verifyWebhook(body, signature, secret) { const expected = crypto .createHmac('sha256', secret) .update(JSON.stringify(body)) .digest('hex'); return crypto.timingSafeEqual( Buffer.from(signature), Buffer.from(expected) ); } // In your handler: const sig = req.headers['x-tuco-signature']; if (!verifyWebhook(req.body, sig, process.env.TUCO_WEBHOOK_SECRET)) { return res.status(401).send('Invalid signature'); } ``` ```python Python theme={null} import hmac, hashlib, json def verify_webhook(body: dict, signature: str, secret: str) -> bool: expected = hmac.new( secret.encode(), json.dumps(body, separators=(',', ':')).encode(), hashlib.sha256 ).hexdigest() return hmac.compare_digest(signature, expected) ``` > [!TIP] > > Your webhook secret is shown **once** when you create the webhook. Save it immediately. > It can't be retrieved later. If you lose it, [rotate the secret](/api-reference/endpoint/rotate-webhook-secret) to get a new one. *** ## Consuming webhooks safely **1. Use messageId + event as your key** Make updates **idempotent**. If you've already processed a `(messageId, event)` pair, ignore duplicates. **2. Move status forward only** Only update your local status in the forward direction (for example `sent` after `queued`). Never move backwards. **3. Return 200 quickly** Tuco expects a `2xx` response within a few seconds. Do heavy processing asynchronously after acknowledging the webhook. **4. Log workspaceId and leadId** These fields let you trace events back to the right tenant and contact in multi-workspace setups. > [!WARNING] > > Tuco does **not** retry webhook delivery. Each event fires once (fire-and-forget). > If your endpoint is down or returns a non-2xx status, that delivery is lost. > Make sure your endpoint is reliable and returns `2xx` quickly. You can use the > [health-check endpoint](/api-reference/endpoint/test-webhook) to verify your endpoint is reachable. # Messages Source: https://docs.tuco.ai/api-reference/messages The message object, lifecycle, and how Tuco processes your sends. Part of the Tuco AI iMessage API reference — bearer-token auth, JSON responses, examples in. ## Overview Every call to `POST /api/messages` creates a message document in Tuco. This page describes the shape of that document, the lifecycle it moves through, and how delivery works under the hood. > [!NOTE] > > Messages sent via API appear in **Unibox** alongside manually sent and incoming > messages. Same recipient = same thread. *** ## Message object **\_id** `string` Unique message ID (MongoDB ObjectId) **message** `string` Body text **messageType** `string` `"imessage"` | `"sms"` | `"email"`. Defaults to `"imessage"` when omitted from the API. **status** `string` Current lifecycle state. See [Status lifecycle](#status-lifecycle) below. **fromLineId** `string` Line used to send **fromLinePhone** `string` Denormalized phone from the line **fromLineEmail** `string` Denormalized email from the line **recipientPhone** `string` Recipient phone number **recipientEmail** `string` Recipient email address **recipientName** `string` Display name **leadId** `string` Linked lead (if any) **workspaceId** `string` Clerk organization ID **createdByUserId** `string` Clerk user ID who created the message **direction** `string` `received` for inbound (a reply from the lead), `sent` for outbound. Inbound messages are where lead-sent photos live. > [accordion] Attachment fields (photos & files) > > **attachmentDownloadUrls** `string[]` > > Present only when the message has attachments. **Public, signed, 30-day URLs — `GET` each one (no auth header) to download the real image/file bytes** with the correct `Content-Type`. This is how you retrieve a photo a lead sent you: the raw `attachmentUrls` below point at private storage and return `403` on their own. > > **attachmentNames** `string[]` > > Filenames aligned 1:1 with `attachmentDownloadUrls` (e.g. `["IMG_1380.jpeg"]`). > > **attachmentUrls** `string[]` > > Raw storage URLs (private for inbound / Tuco-hosted). Kept for reference — use `attachmentDownloadUrls` to fetch bytes. > [accordion] Scheduling & settings fields > > **scheduledDate** `string` > > ISO 8601 timestamp — when to send > > **batchId** `string` > > Grouping identifier > > **stepIndex** `number` > > Sequence step index (0 = step 1) > > **settings** `object` > > Time window settings: > > **settings fields** > > **timezone** `string` > > IANA timezone > > **sendWindowStart** `string` > > HH:mm > > **sendWindowEnd** `string` > > HH:mm > > **allowedDaysOfWeek** `number[]` > > 0=Sun … 6=Sat > [accordion] Delivery tracking fields > > **sentAt** `string` > > When actually sent > > **deliveredAt** `string` > > When delivery confirmed via device callback > > **readAt** `string` > > When read (incoming messages only) > > **externalMessageId** `string` > > device message ID > [accordion] Error & fallback fields > > **errorMessage** `string` > > Error details when `failed` or `fallback` > > **checkedAddresses** `string[]` > > Addresses checked for iMessage availability (on `fallback`) > > **sendFallbackSmsOnFailed** `boolean` > > When `true` + message fails, Tuco sends fallback SMS if Twilio is configured. > Default: `false`. > [accordion] Integration fields > > **hsContactId** `string` > > HubSpot contact ID > > **hsPortalId** `string` > > HubSpot portal ID > > **ghlContactId** `string` > > GHL contact ID > > **ghlLocationId** `string` > > GHL location ID > > **ghlConversationMessageId** `string` > > GHL conversation message ID > > **closeOrgId** `string` > > Close organization ID (`orga_…`) > > **closeLeadId** `string` > > Close Lead ID (`lead_…`) — the record the Close activity attaches to > > **closeContactId** `string` > > Close Contact ID (`cont_…`) **createdAt** `string` Creation timestamp **updatedAt** `string` Last update timestamp *** ## Status lifecycle ``` queued → pending → sending → sent → delivered ↘ failed ↘ fallback ↗ scheduled (rescheduled) cancelled ``` | Status | Meaning | | - | - | | **queued** | Not yet picked for send (waiting for line limits, time window, device gap, or contact gap) | | **pending** | Assigned to a line, worker is processing | | **sending** | Worker is actively sending (prevents duplicate sends) | | **sent** | Accepted by the provider (iMessage relay / Twilio) | | **delivered** | Delivery confirmed via device callback (can come later) | | **failed** | Technical send failure after all retries, or availability API error | | **fallback** | Availability check determined recipient has no iMessage | | **scheduled** | Will send at `scheduledDate`, or rescheduled due to device gap | | **cancelled** | User or system cancelled | > [!TIP] > > **`sent` vs `delivered`:** `sent` means the provider accepted the message. > `delivered` means the recipient's device confirmed receipt — this can arrive > seconds or minutes later via a device callback. *** ## Pre-send checks (why a message stays queued) These checks run **before** a message is sent. None of them cause an API error — the message is accepted and waits. | Check | What it does | If it fails | | - | - | - | | **Time window** | Only send inside `sendWindowStart`–`sendWindowEnd` on `allowedDaysOfWeek` | Stay **queued** until next valid time | | **Line limits** | Daily total messages / daily new conversations per line | Stay **queued** until limits reset | | **Device gap** | Minimum time between sends from the same physical device (default **30s**) | **Queued** or **rescheduled** | | **Contact gap** | Minimum time between first messages to different contacts on the same line (default **45s**) | Stay **queued** | > [!NOTE] > > You can check why a message is still queued by looking at the message status API > logs for events like `individual.message.validation_failed`, > `message.queued_limit`, `individual.message.device_gap_not_met`, > or `individual.message.gap_not_met`. *** ## Retries | Context | Send attempts | Verification between attempts | Gap | Env vars | | - | - | - | - | - | | **Individual** (API / Unibox) | **5** | `outgoing_messages` + device gateway `message/query` (poll up to 90s) | 60s | `UNIBOX_REPLY_RETRY_*` | | **App sync fallback** | **3** | Same as individual | 30s | `SYNC_FALLBACK_RETRY_*` | > [!NOTE] > > The "app sync fallback" path only runs when the BullMQ queue is unreachable > (e.g. Redis down). In normal operation, the worker handles all sends. *** ## Replying via API There is no special "reply" endpoint. To reply to a conversation, send another message to the **same recipient** using `POST /api/messages`. Unibox groups messages by recipient, so the new message appears in the existing thread. *** ## Where messages appear | Surface | What you see | | - | - | | **Unibox** | Per-message status icon + label. All statuses except `queued`, `scheduled`, and `cancelled`. | | **API** | `GET /api/messages` with filters by status, line, lead, etc. | # Upload Attachment Source: https://docs.tuco.ai/api-reference/upload-attachment POST /api/attachments/upload Upload an audio clip, image, video, or PDF and get a public URL to use as an attachmentUrl. REST endpoint in the Tuco AI iMessage API — bearer-token auth. > [!NOTE] > > Use this endpoint to turn a local file into a **public, workspace-owned URL** you can > drop straight into [`attachmentUrls`](/api-reference/endpoint/send-with-attachments) on > `POST /api/messages` or into the GHL **Send voice note** action. The URL is signed for > your workspace, so it always passes the "does not belong to this organization" guard — > no need to host the file yourself. ## Authentication Pass your workspace API key as a Bearer token (the **same key** as `/api/messages`), or use a Clerk session token. ```bash theme={null} Authorization: Bearer tuco_xxxxxxxxxxxxx ``` *** ## Request Send a `multipart/form-data` request with a single **`file`** field. There is **no JSON body** — this is a file upload, so `Content-Type: application/json` is rejected with `400 Expected multipart/form-data with a "file" field.` The file is capped at **5 MB** and the type is validated by file **extension** (browsers report unreliable MIME for `.caf` and `.heic`). > [!NOTE] > > 5 MB is the **upload** limit, not iMessage's. A message attachment supplied as a public > URL (`attachmentUrls` on [send-message](/api-reference/endpoint/send-message)) can still > be up to 25 MB — that file never passes through Tuco. Uploads are held lower because they > stream through our servers, and because a voice note is capped at 5 minutes of audio anyway. ### Allowed types | Category | Extensions | Use | | - | - | - | | Audio (voice notes) | `mp3`, `m4a`, `wav`, `aac`, `ogg`, `caf` | Source for a native iMessage voice note (with `voiceNote: true`) | | Images | `png`, `jpg`, `gif`, `webp`, `heic` | Inline image attachment | | Video | `mp4`, `mov`, `webm` | Playable video attachment | | Documents | `pdf` | Attachment preview | > [!NOTE] > > **Voice notes:** upload any of the audio formats above. When the file is used with > `voiceNote: true` (GHL action) or otherwise flagged for a voice note, the worker > transcodes it to the native iMessage voice-note bubble — you do **not** have to convert > to `.caf` yourself first. *** ## Example ```bash Upload an audio clip theme={null} curl -X POST "https://app.tuco.ai/api/attachments/upload" \ -H "Authorization: Bearer tuco_xxxxxxxxxxxxx" \ -F "file=@/path/to/voice-note.m4a" ``` ```bash Upload an image theme={null} curl -X POST "https://app.tuco.ai/api/attachments/upload" \ -H "Authorization: Bearer tuco_xxxxxxxxxxxxx" \ -F "file=@/path/to/photo.jpg" ``` *** ## Response Returns **`200 OK`** with the public URL and file metadata. ```json theme={null} { "url": "https://app.tuco.ai/api/attachments/crm-media/...?sig=...&exp=...", "name": "voice-note.m4a", "size": 84213, "contentType": "audio/mp4", "workspaceId": "org_3AZs4H8UsfFxVFONr6H4K75okaG" } ``` **url** `string` A **public, signed link** hosted on your workspace storage. Use it directly as an `attachmentUrl` — it needs no auth to fetch and always passes the `/api/messages` org-ownership guard. Valid for **\~1 year**; re-upload if a workflow may run longer. **name** `string` The original filename you uploaded. **size** `number` File size in bytes. **contentType** `string | null` The uploaded file's MIME type, or `null` when the browser/client didn't report one (common for `.caf`/`.heic`). Delivery does not depend on this field. **workspaceId** `string` The Clerk organization ID that owns the file — the workspace your API key belongs to. > [!TIP] > > Copy the returned `url` straight into the GHL **Send voice note** action's `attachmentUrl` > field, or into `attachmentUrls` on [`POST /api/messages`](/api-reference/endpoint/send-with-attachments). > Because the file lives under your workspace, it passes the ownership guard automatically. *** ## Using the URL **1. Upload the file** `POST /api/attachments/upload` with your audio/image/etc. as the `file` field. Grab `url` from the response. **2. Send it** Pass `url` as an `attachmentUrl` — in `attachmentUrls` on [`POST /api/messages`](/api-reference/endpoint/send-with-attachments), or in the GHL [**Send voice note**](/integrations/ghl#send-a-voice-note-from-ghl) action. **3. Re-upload if it's older than a year** The signed link is valid for \~1 year. For a long-running workflow, re-upload periodically so the URL never expires mid-sequence. *** ## No-code alternative: the Uploads UI You don't need to call the API to get a URL. In the dashboard: * **`/uploads`** — a dedicated **Upload audio etc** page. * The **Upload audio etc** tab on the **Leads** page. Both give you a drag-and-drop dropzone. Drop a file (or click to choose), then hit **Copy** to copy the public link — the same URL this endpoint returns. Audio files get a 🎙 *Voice-note ready* badge and an inline preview player. > [!TIP] > > This is the fastest path for a one-off voice note: record it, drop it on **/uploads**, > copy the link, and paste it into the GHL **Send voice note** action's Attachment URL. *** ## Errors | Status | When | Body | | - | - | - | | `401` | Missing or invalid API key / session | `{ "error": "Unauthorized" }` | | `400` | Not `multipart/form-data` / no `file` field | `{ "error": "Expected multipart/form-data with a \"file\" field." }` | | `400` | `file` field missing | `{ "error": "No file provided (multipart field \"file\")." }` | | `400` | File is empty (0 bytes) | `{ "error": "File is empty." }` | | `400` | Unsupported extension | `{ "error": "…: unsupported type. Allowed: mp3, m4a, wav, …" }` | | `413` | File over 5 MB | `{ "error": "File is N MB. Attachments must be under 5 MB." }` | | `413` | Audio over 5 MB | `{ "error": "NAME is N MB. Audio must be under 5 MB — a voice note can only be 5 minutes long. Trim or compress the recording." }` | # Health, Reliability & Limits Source: https://docs.tuco.ai/architecture/health-checks What you can expect from Tuco AI when things are healthy or under strain. Design notes for builders integrating with the Tuco AI iMessage platform on dedicated. ## When Everything Is Healthy When Tuco AI is healthy: * Messages you schedule or send flow out in a steady, predictable way. * Lines you have set up behave as expected in the app and in reporting. * Webhooks and exports reflect recent activity without surprises. No action is required from you to “keep it running” day to day; the system automatically looks after its own internal checks. *** ## What You See If Something Is Wrong If Tuco cannot send or update something the way you expect, it focuses on making that visible rather than hiding it. You may notice: * Message statuses in the app that clearly show something did not go through. * Scheduled messages that appear stuck or not progressing. * Fewer events or updates reaching your own systems than usual. In all of these cases, your existing data remains intact. Tuco does not silently alter or discard messages or leads when a problem occurs. *** ## How Limits Affect You Tuco applies sensible limits to protect recipients, sending accounts, and overall service quality. From your point of view, this means: * Very large bursts of activity may be spread out over time instead of going out all at once. * Attempts that would exceed safe or documented limits are clearly declined rather than partially accepted. * The same safeguards apply whether activity comes from the UI or the API, so behavior stays consistent. Data is preserved safely: if a send is held back or rejected for limit reasons, you can still see the relevant records and decide what to do next. *** ## Your Role in Monitoring You remain in control of how closely you watch Tuco from your side. Common patterns include: * Glancing at message and line overviews in the app to confirm activity looks normal. * Using your own dashboards, based on Tuco data or webhooks, to watch high‑level volumes and success rates. Tuco’s responsibility is to make outcomes clear and stable; your responsibility is to decide how much additional visibility you want in your own tools. # Architecture Overview Source: https://docs.tuco.ai/architecture/overview How Tuco AI is structured from a customer’s point of view. Design notes for builders integrating with the Tuco AI iMessage platform on dedicated Apple hardware. ## How Tuco AI Is Organized Tuco AI is organized around a few clear areas you interact with: * The main app, where you manage leads, lines, and settings. * The delivery engine, which turns what you configure into real messages. * Integrations and APIs, which let your existing tools work with Tuco data. From your perspective, these pieces act as one product: changes you make in the app flow through to sending, reporting, and integrations without extra setup. *** ## What This Means for Your Team Because the product is structured this way: * Updates you make in Tuco (like changing a lead or a line) are reflected consistently wherever they matter. * Your CRM or internal tools can safely read from and write to Tuco using the documented APIs. * Everyone on your team sees the same truth in the Tuco UI, exports, and connected systems. The system automatically handles how these parts talk to each other; you only decide what you want to run and where data should show up. *** ## Reliability & Isolation Tuco AI is designed so that: * Workspaces are clearly separated, and one customer’s activity does not interfere with another’s. * Issues in connected tools or channels do not silently change your data in Tuco. * When something cannot be sent or synchronized, you see clear statuses and messages rather than silent failures. Data is preserved safely, and you stay in control of when to retry, change configuration, or pause activity. *** ## How Integrations Fit In Integrations such as CRM plugins and custom backends connect to Tuco using the same public APIs and webhooks you see in the docs. This gives you: * Predictable data shapes between Tuco and your systems. * A single place (your Tuco workspace) to manage what is allowed to connect. * Confidence that turning an integration on or off has obvious, visible effects. No action is required from you to understand internal components; the only surfaces you need are the app, the APIs, and the webhooks you explicitly configure. # How Tuco Sends Messages Source: https://docs.tuco.ai/architecture/workers What you can expect from Tuco’s sending engine without looking under the hood. Design notes for builders integrating with the Tuco AI iMessage platform on. ## From Setup to Sending Once you have configured lines and leads in Tuco, the sending engine quietly turns that configuration into real outreach. From your perspective: * Messages you schedule appear in Tuco with clear statuses. * Changes you make to leads and lines are respected going forward. * Activity is reflected in analytics, exports, and webhooks in a consistent way. The system automatically handles timing, ordering, and delivery details so you can focus on who you contact and what you say. *** ## Predictable Message Behavior Tuco is designed so that message behavior feels predictable: * Messages that are accepted for sending will either complete with a visible final state or remain clearly marked as not sent. * Pausing a line or cancelling scheduled messages stops new sends from starting, while already‑sent messages remain in history. * Resuming activity continues from the current state, without silently replaying past sends. No hidden resends or silent drops are introduced by the sending engine; what you see in Tuco is what happened. *** ## Fair Use of Your Lines Tuco treats your lines as shared capacity that should be used fairly and safely. In practice, this means: * Individual lines are not pushed beyond the usage levels Tuco considers safe for that identity. * Activity is spread in a way that avoids obvious spikes that could harm deliverability or trust. If a line cannot be used safely, Tuco makes that visible in the product instead of quietly over‑using it. *** ## Working Alongside Integrations Messages sent from integrations (such as CRMs or custom backends) go through the same sending engine as messages you configure directly in Tuco. As a result: * Your team sees one unified history of outreach, regardless of where it started. * Limits and protections apply consistently across all sources. * Webhooks and analytics reflect the full picture, not just what originated in the UI. No extra configuration is needed to “turn on” this consistency; it is handled automatically by the system as soon as you connect an integration. # FAQ & Troubleshooting Source: https://docs.tuco.ai/faq Answers to common questions about Tuco AI: choosing a line and fromLineId, iMessage availability, background workers, webhooks, failures and integrations. ## General Usage > [accordion] What is a 'line' in Tuco AI? > > A **line** is your sending identity in Tuco AI. > > * It represents a specific phone/email/iMessage identity. > * Each line has: > * Daily new conversations and total message limits. > * Health status (healthy/unhealthy). > * Usage counters for the current day. > > When sending via the API, you must choose a `fromLineId`.\ > Use `/api/lines/by-user` to list and filter active, healthy lines. > [accordion] What's the difference between Quick Send and sending to leads? > > **Quick Send**: > > * One-off message, no need to create a lead. > * Ideal for testing or ad-hoc outreach. > * Can still use availability checks and scheduling. > > **Send to Leads**: > > * Uses leads stored in Tuco. > * Integrated with availability and reporting. > * Best for repeatable, large-scale outreach. > [accordion] How does Tuco choose between iMessage, SMS, and email? > > Tuco uses a combination of: > > * **Availability checks** to determine iMessage support per address. > * **Message type** (`imessage`, `sms`, `email`) you specify. > * **Fallback rules** when iMessage is unavailable. > > See `/features/check-availability` and `/features/failures-and-fallbacks` for the complete decision logic. *** ## Availability & Fallbacks > [accordion] How does iMessage availability checking work? > > Tuco checks all available contact addresses for a lead in a prioritized order: > > 1. Primary phone > 2. Primary email > 3. Alt phones (1–3) > 4. Alt emails (1–3) > > It queries your configured iMessage bridge and stops at the **first address that supports iMessage**. > > If none support iMessage: > > * The lead is marked as "unavailable" for iMessage. > * Sends to leads and Quick Send can fallback to SMS/email depending on your settings. > [accordion] What happens if a recipient does not have iMessage? > > When the system determines that a recipient (across all their addresses) does **not** support iMessage: > > * The worker emits a `message.fallback` webhook with: > * `event: "message.fallback"` > * A `reason` string describing why iMessage is unavailable. > * `checkedAddresses` for debugging. > * Your app can then: > * Route the message via SMS or email. > * Flag the lead's iMessage availability as unavailable. > [accordion] Do availability checks ever mark a message as 'failed'? > > No. Availability checks are used to choose routes and mark leads' capabilities. > > * Messages are typically: > * Sent via iMessage if available. > * Marked as `fallback` when iMessage is unavailable. > * Availability logic itself does **not** cause messages to be marked `failed`; health and provider errors do. *** ## Queueing & Workers > [accordion] Why are many messages stuck in 'queued'? > > Common causes: > > * Daily limits reached for one or more lines: > * `dailyNewConversationsLimit` exceeded. > * `dailyTotalMessagesLimit` exceeded. > * Your configured **time window** has not opened yet. > * The current day is not in **allowed days of week**. > * Gap enforcement between contacts on a line has not been satisfied. > > These are **normal throttling conditions**, not failures. Messages remain `queued` and will be retried in future worker runs. > [accordion] Can a queued message become 'failed' just because limits are reached? > > No. Hitting: > > * Daily new conversation limits, > * Daily total message limits, > * Time windows, > * Allowed days of week, or > * Gap constraints > > does **not** directly cause a message to become `failed`. Instead, the message remains `queued` until conditions allow it to be processed. *** ## Line Health & Failures > [accordion] What happens if a line goes offline? > > For a lead that already **received prior messages** from that line: > > * Remaining queued messages for that lead on the failed line are marked `failed`. > * Reason: "Line became inactive after previous messages were sent". > * We **do not** reassign to a different line to preserve conversation continuity. > [accordion] Why do I see many 'failed' statuses? > > Likely causes: > > * Persistent line health issues (device/app offline, misconfigured server URL). > * Provider-level hard errors (invalid numbers/emails, blocked sends). > * Misconfigured workers endpoint for message webhooks or health checks. > > Investigate: > > * Line health in your Tuco dashboard. > * Worker logs for error messages. > * Underlying iMessage/SMS provider status. > [accordion] How do per-line limits interact with multiple sends? > > Limits are per line, per day: > > * Workers compute usage across **all messages** from a line when deciding if a new message is allowed. > > If one large send uses up capacity on a line, other messages on the same line may remain `queued` until the next day. > [accordion] What happens when I hit the daily message limit on a send (e.g. POST /api/messages)? > > When a line has reached its **daily message limit** and you call the send API (e.g. **POST /api/messages**), Tuco does **not** return an error or drop the message. It **accepts the request** and defers send to the next available window. > > **What you get back (201):** > > * `success: true` > * `status: "scheduled"` > * `scheduledDate`: ISO timestamp when the message becomes eligible to send (default: **09:00 the next day in your workspace's time zone**, or your `settings.sendWindowStart`). Held messages are released gradually under the line's pacing, so some go out shortly after this time. > * `reason`: e.g. `"Daily limit reached; scheduled for next send window."` > > **For revops / GTM pipelines:** > > * Treat **201** with `status: "scheduled"` as success: the message is queued and will send automatically at `scheduledDate`. No retry needed. > * Use `scheduledDate` in your CRM or analytics to show “sends at” so sales and marketing see accurate timing. > * To align with a specific region, send `settings.timezone` (e.g. `America/Los_Angeles`) and optionally `settings.sendWindowStart` (e.g. `"09:00"`) in the request body so the next send window matches that timezone. > > **Limits:** Daily limits are per line and reset at midnight in your workspace's time zone. The deferred message counts toward the limit on the **day it is actually sent**, not the day the API was called. *** ## Webhooks > [accordion] What webhooks should I implement first? > > At minimum: > > * **Message webhooks** (`/api-reference/message-webhooks`): > * `message.sent` > * `message.fallback` > * Optionally, generic `/webhook` events from `/api-reference/endpoint/webhook` for: > * `lead.created`, `lead.updated`, `availability.checked`, etc. > > Implementing these gives you: > > * Accurate message stats in your own systems. > * A foundation for CRM sync and analytics. > [accordion] How should I secure message webhooks from workers? > > Use a shared **service token**: > > * Configure a `SERVICE_TOKEN` env variable in your app and workers. > * Require `Authorization: Bearer ` or `X-Service-Token: ` on `/api/webhooks/v1-message`. > * Reject any requests where the token does not match. > [accordion] Do I need to support retries or idempotency? > > Yes. > > * Webhooks are retried when your endpoint: > * Times out. > * Returns non-2xx responses. > * You should: > * Implement idempotency by `(messageId, event)` combination. > * Make database updates idempotent (e.g. upserts or `updateOne` with `$set`). *** ## API & Integration Questions > [accordion] Which token should I use for the API: Clerk token or Tuco API key? > > * For **first-party** use (your own backend talking to the Tuco app), Clerk or Tuco auth tokens may be used per the `/api-reference/introduction`. > * For **integrations** (e.g. HubSpot backend, third-party services), use a dedicated **Tuco API key**: > * Easier to rotate. > * Clean workspace scoping. > * Safer to store in environment variables. > [accordion] How do I handle 402 READ\_ONLY errors? > > `402 READ_ONLY` means the workspace is temporarily in **read-only mode**, often due to billing. > > * Do not keep retrying writes; they will continue to fail. > * Surface a clear message in your UI: > * “Tuco workspace is in read-only mode, please update billing in Tuco.” > * Reads may still work; only writes are blocked. > [accordion] Can I use Tuco from my front-end directly? > > Direct front-end use is **not recommended**: > > * You would have to expose API keys or secure tokens in client code (unsafe). > * It is harder to centralize error handling, rate limiting, and idempotency. > > Recommended pattern: > > * Your front-end calls **your backend**. > * Your backend calls Tuco APIs with secure credentials. *** ## HubSpot Integration > [accordion] How does the HubSpot integration talk to Tuco? > > The HubSpot backend (`plugins/hubspot-backend`) uses: > > * HubSpot OAuth to get CRM permissions. > * A workspace-specific **Tuco API key** to: > * List lines (`/api/lines/by-user`). > * Send messages (`/api/messages`). > * Record activity back in HubSpot via timeline events. > [accordion] What if a HubSpot workflow action fails to send? > > Likely causes: > > * Missing/invalid Tuco API key. > * No active lines in the Tuco workspace. > * HubSpot contact missing phone/email. > > Check: > > * Backend logs for `actions.routes.ts` and `tuco.service.ts`. > * That you have at least one active line in Tuco. > * That contact data in HubSpot maps correctly to Tuco fields. # Integrations FAQ Source: https://docs.tuco.ai/faq/integrations FAQ for connecting Tuco AI to CRMs, backends, and other systems using only public APIs. From the Tuco AI team — outbound iMessage automation for B2B and B2C. ## General Integration Patterns > [accordion] Does Tuco work with Customer.io? > > Yes. A Customer.io journey's Webhook action calls `POST /api/messages` to send, and Tuco's message webhooks feed a webhook-triggered Customer.io journey that records sends, replies and failures as events on the person. No Zapier or n8n is needed. Step-by-step: [Send iMessage from Customer.io](/guides/send-imessage-from-customer-io). > [accordion] What is the recommended way to integrate my backend with Tuco? > > Recommended pattern: > > * **Your front-end**: > * Talks only to your own backend. > * Never holds Tuco API keys. > * **Your backend**: > * Stores a **workspace-scoped Tuco API key** securely. > * Calls Tuco’s public APIs for: > * Lead creation/import. > * Message sending. > * Line listing. > * Exposes its own internal APIs to your applications. > * **Webhooks**: > * You configure Tuco to send message and other webhooks to your backend. > * Your backend processes them and updates your internal systems (CRMs, data warehouse, etc.). > [accordion] Can I integrate Tuco directly into my CRM? > > Yes, and the HubSpot integration is a good reference architecture: > > * A **CRM-side app**: > * Provides UI inside the CRM (cards, workflow actions, settings). > * A **backend connector**: > * Knows how to talk to the CRM API. > * Uses a Tuco API key to talk to Tuco. > > The same pattern is what [GoHighLevel](/integrations/ghl) and [Close](/integrations/close) use. You can adopt it for other CRMs (Salesforce, Pipedrive, etc.), always: > > * Using Tuco’s documented APIs. > * Never calling internal worker endpoints or databases directly. *** ## Webhooks & Events > [accordion] Which webhooks are essential for a robust integration? > > At a minimum: > > * **Message webhooks**: > * Delivery and fallback events, as documented in `/api-reference/message-webhooks`. > * **Generic event webhooks** (where configured): > * `lead.created`, `lead.updated`, `availability.checked`, etc. > > Using these, your integration can: > > * Keep message statuses in sync. > * Update contact availability. > * Trigger follow-up actions in your own systems. > [accordion] How do I ensure webhooks don't overload my system? > > Strategies: > > * Implement a light **ingress layer**: > * Validates and authenticates requests. > * Quickly enqueues them to your own internal queue. > * Responds to Tuco within a short timeout. > * Process webhook payloads asynchronously: > * Database writes and downstream calls happen in background workers. > * Use backpressure and rate limiting internally: > * Ensure a spike in events from Tuco does not overwhelm downstream dependencies. *** ## HubSpot-Specific Questions > [accordion] How is the HubSpot app linked to my Tuco workspace? > > The HubSpot backend: > > * Uses HubSpot OAuth to identify the HubSpot account. > * Asks the user to either: > * Authenticate with Tuco, or > * Provide a Tuco API key. > * Stores the mapping: > * HubSpot portal ↔ Tuco workspace ↔ Tuco API key. > > After this: > > * Workflow actions and cards know which Tuco workspace to talk to. > * All calls from the backend to Tuco use the stored API key. > [accordion] What data flows from Tuco back into HubSpot? > > Typical flows include: > > * **Timeline events**: > * Outbound Tuco messages (content, channel, status). > * Replies from recipients as inbound events. > * **Status updates**: > * Flags or properties that indicate last contacted/last replied dates. > > All of this happens through: > > * Tuco → HubSpot backend via public webhooks and APIs. > * Backend → HubSpot via officially supported HubSpot APIs. # Security, Access & Billing FAQ Source: https://docs.tuco.ai/faq/security-billing Frequently asked questions about Tuco AI API keys, workspace access, read-only mode, billing, secret-rotation, and safe usage patterns for production teams. ## API Keys & Access > [accordion] How should I store and use Tuco API keys? > > Best practices: > > * Store API keys **only on your backend** (server-side). > * Use secure secret management (e.g. environment variables, secret managers). > * Never embed keys in: > * Front-end JavaScript. > * Mobile/desktop apps distributed to end-users. > * Public repositories or logs. > > For each workspace or integration: > > * Prefer a dedicated **workspace-scoped** API key instead of sharing one key across many systems. > [accordion] Can I use the same key for multiple environments? > > It is recommended to: > > * Use separate API keys for: > * Development. > * Staging. > * Production. > > This allows you to: > > * Isolate data and actions per environment. > * Rotate keys independently as needed. *** ## Authentication & Authorization Behavior > [accordion] What does a 401 Unauthorized mean in Tuco? > > A `401 Unauthorized` typically means: > > * The `Authorization` header is missing. > * The token or API key is not valid. > * The token is not accepted for the requested endpoint. > > Check: > > * Token format (e.g. `Authorization: Bearer `). > * That the key corresponds to the intended workspace and environment. > [accordion] What does a 403 Forbidden mean? > > A `403 Forbidden` indicates: > > * You are authenticated, but not allowed to perform this action or access this resource. > > Common cases: > > * Attempting to access resources not belonging to the workspace associated with your token. > * Using a token with insufficient privileges (where granular roles are configured). *** ## Billing, Read-Only Mode & Quotas > [accordion] What is READ\_ONLY mode and how does it affect my integration? > > When a workspace enters **read-only** mode (e.g. due to billing issues), write operations may fail with: > > ```json theme={null} > { > "error": "READ_ONLY", > "code": "READ_ONLY", > "reason": "past_due" > } > ``` > > Effects: > > * You may still be able to **read** data (e.g. leads, messages, lines). > * **Writes** such as creating new messages or leads will be blocked. > > Integration guidance: > > * Treat this as a **hard stop** for writes. > * Surface clear messaging in your own UI or logs: > * “Tuco workspace is in read-only mode; please resolve billing in Tuco.” > * Avoid infinite retries; they will continue to fail until resolved. > [accordion] How do plan limits interact with daily message limits? > > At a high level: > > * **Plan limits**: > * Define global ceilings (e.g. total messages per day or month per workspace). > * **Per-line limits**: > * Define how many messages a specific line can send in a day. > > Workers enforce per-line limits; the app enforces workspace-level plan constraints.\ > Together, they ensure: > > * No single line is overused. > * Entire workspaces stay within contracted limits. *** ## Data Privacy & Isolation > [accordion] How is my workspace data isolated from others? > > Workspaces provide logical isolation: > > * Each workspace has its own: > * Leads. > * Messages. > * Lines and configuration. > > Access decisions are always scoped by: > > * The workspace associated with the authenticated user or API key. > > Tuco does not allow cross-workspace reads or writes via public APIs. > [accordion] Can Tuco staff see my messages and leads? > > Operational behavior depends on contractual and legal requirements; in general: > > * Access to data by Tuco personnel is restricted and audited. > * Where sensitive environments require it, additional controls can be applied via: > * Support agreements. > * Data processing addenda. > > For compliance-specific guarantees (e.g. SOC 2, GDPR), refer to your contract and official legal/compliance documentation provided by Tuco outside of this developer guide. # Background Processing & Reliability FAQ Source: https://docs.tuco.ai/faq/workers What you can expect from Tuco’s behind-the-scenes processing, without needing to know the internals. From the Tuco AI team — outbound iMessage automation for. ## How Tuco Works Behind the Scenes (From Your Perspective) Tuco uses background processing to turn your configuration and API calls into real‑world messaging activity. You don’t see the internal jobs or queues; you only see **observable behavior**: * Messages move through clear, stable statuses. * Limits and time windows are respected without manual intervention. * Webhooks and analytics reflect what has actually happened. This FAQ explains what you can expect from that behavior and how to design integrations that work well with it—without exposing any proprietary implementation detail. *** ## Scheduling & Frequency ### How quickly will my messages start sending? Once you: * Have active lines, * Send or schedule messages, and * Are within your allowed time windows and limits, you should see messages begin to move from “planned” states (e.g. queued) to “sent/delivered” over the next few minutes. Tuco’s internal schedulers: * Continuously evaluate which messages are eligible to send. * Apply your limits and timing rules. * Move eligible messages forward without you having to poll or push them manually. You never need to run your own cron jobs against Tuco; you only react to the outcomes you see in the API, UI, and webhooks. *** ### Are sends guaranteed to be “exactly once”? At the level of your own data, Tuco is designed for **effectively‑once** behavior: * A given message record moves forward through its status lifecycle (queued → sent/delivered/failed/fallback). * Webhooks include stable identifiers so you can safely treat duplicates as no‑ops. From your perspective: * You should design your webhook consumers and internal updates to be **idempotent**: * Applying the same event twice should not corrupt data. * You can always check current status before “moving backwards”. You do not need to know how many internal retries happened—only that the end state you see is authoritative. *** ## Observability & Debugging (Customer View) ### How can I tell if background processing is falling behind? Use Tuco’s visible surfaces and your own instrumentation: * In Tuco: * Watch message stats: * Growing **queued** counts that never move to **sent/delivered**. * Unusual patterns in failed or fallback counts. * Check line‑level views for health and usage. * In your own systems: * Plot message webhooks over time. * Watch for a drop in delivery or reply events when you expect activity. If messages stay queued for much longer than your typical pattern—even when you are within limits and time windows—that’s a signal to contact Tuco support or check any status page you’ve been provided. *** ### What logs should I rely on when debugging issues? You never need access to Tuco’s internal logs to debug typical issues. Instead, rely on: * **Your own application logs** * API requests and responses to/from Tuco. * When you created messages or changed settings. * **Webhook logs on your side** * Incoming message outcome events (delivered, fallback, failed). * Incoming reply events. * Any errors or timeouts in your webhook handlers. * **Tuco UI and APIs** * Message history and status for specific leads. * Counts and charts in the app that show throughput and outcomes. By correlating: * When you created or updated something, * What Tuco shows in its UI and APIs, * What webhooks you received, you can reconstruct what happened without needing to see any worker or queue internals. *** ## Integration Considerations ### Do I need direct access to any internal processing services? No. * All integrations should use: * The **public Tuco APIs** for reads and writes. * The documented **webhooks** for event notifications. * Internal worker processes are an implementation detail Tuco can change without affecting your contracts. This gives you: * A stable, documented surface to build on. * Confidence that upgrades to Tuco’s internals won’t break your integration. *** ### How should I handle out-of-order or duplicate events? Because Tuco uses asynchronous processing and safe retry behavior, you may occasionally see: * Duplicate webhook events. * Events that arrive slightly out of order (for example, a delivered event arriving close in time to a sent event). Design your systems to be: * **Idempotent** * Identify events using the IDs in the webhook payload. * If you have already applied an event for a given message and status, treat the duplicate as a no‑op. * **Monotonic** * Only move your local status **forward** (e.g. from queued → sent → delivered). * Ignore any event that would move a message backwards in your own records. Following these patterns is enough; you never need to reason about Tuco’s internal queues or retry policies. *** ## Reliability Guarantees (From Your Side) Tuco’s background processing is built so that: * Your data is preserved safely. * Errors are surfaced as clear outcomes, not silent drops. * Limits and safety rules apply consistently across UI and API usage. From your perspective: * A write either: * Succeeds and shows up in the UI and APIs, or * Fails with a clear, documented error. * A message either: * Reaches a visible outcome state (sent/delivered/failed/fallback), or * Remains in a clearly non‑terminal state (queued/pending) while it is still being considered. You can confidently build: * Automations keyed off of these states. * Dashboards that compare planned vs completed sends. * Alerting around sudden changes in outcome patterns. All without needing any visibility into Tuco’s internal workers, queues, or infrastructure layout. # Anti-Spam & Messaging Rules Source: https://docs.tuco.ai/features/anti-spam-guidelines Keep your Tuco AI iMessage line healthy: be a real person, message only opt-in leads, and avoid the spam-reports that trigger an Apple ban. Almost everything about staying off Apple's spam radar comes down to a single rule: **every account should look and feel like a real person, not a brand.** A real first and last name, plus a real profile photo of the actual salesperson who'll handle the conversation. When the lead reads your message, it should feel like an individual texted them — not a company. The two columns below are roughly 90% of what matters. The rest of this page explains *why* each rule exists. > [card] Do > > * Only message **opt-in / warm leads** (see [Who you can message](#who-you-can-message)). > * Use a **real person's full name** — the salesperson who'll reply. > * Use a **real headshot** of that person as the profile picture. > * Write like a human texting one person: short, conversational, specific. > * **Wait for them to reply** before sending any link or image. > [card] Don't > > * Don't put a **link in the first message**. > * Don't send **images or attachments** before they reply. > * Don't write promotional copy that reads like an **SMS blast** or a marketing email. > * Don't use a **business / brand / product / role name** as the sender. > * Don't use a **logo, product screenshot, or stock photo** as the profile picture. > * Don't message **cold lists, purchased lists**, or anyone who never opted in. *** ## Who you can message iMessage outreach is allowed **only** to people who took an action with you. These are warm, opt-in audiences: * Responded to your Facebook ads * Responded to your Google ads * Filled out a form * Booked a demo * Had a conversation with you * Purchased from your ecommerce store * Gave you their phone number directly > [!WARNING] > > Cold lists, purchased lists, and anyone who never opted in are off-limits. There is no list size or warm-up trick that makes cold sending safe — it is the fastest way to a spam report and a ban. *** ## Why this matters The rules above aren't branding preferences. They're what keeps your Apple ID sending blue bubbles instead of getting restricted. Here's the mechanism, step by step: **1. A new contact can report you** When you message a new contact, they can mark you "known" or report you as "spam." This happens even with warm leads — they forgot they signed up, typo'd their number, or simply changed their mind about opting in. **2. A spam report lifts encryption on that thread** iMessages are end-to-end encrypted by default — normally only the sender and recipient can read them. The moment someone reports a conversation as spam, that protection lifts and Apple can review the past messages in that thread for quality control. **3. Obvious automation gets the Apple ID restricted** If that review makes it obvious the messages are automated and coming from a business, Apple restricts iMessage on that Apple ID. The number stops sending blue iMessages and shows up as a **green SMS bubble** — a clear signal to recipients that something changed. **4. The free unban favors real people** Apple offers a **one-time free unban**. The key detail: that free unban almost never works when the account is set up under a business name. It works far more reliably when the account looks like a genuine person. That is the single biggest reason for the real-name and real-photo rule. *** ## Sender names — good vs risky The sender name is the first thing a recipient sees. Make it a person. > [card] Good — real human names > > * James Carter > * Priya Nair > * Marcus Webb > * Elena Rossi > [card] Risky — brand / role / product > > * Sandy Vans Sales > * Riverx AI > * The Acme Team > * Support Desk > * Info Outreach Real fixes from actual customers: * **"Sandy Vans"** → Braden Gross or Tanner Hendrix * **"Riverx AI"** → Brad Bone Pick the human who will actually handle the replies. *** ## Numbers & email aliases aren't guaranteed We target the identity you want, but availability is set by the carrier and by Apple — so we can't promise an exact match. > [card] Phone numbers > > We target by **region / ZIP code** — e.g. you can get a 212 number in New York — but we **cannot guarantee** a number that starts with a specific area code (e.g. "must start with 914"). If your preferred code isn't available, we provision the nearest available number in that region. > [card] Email lines > > Give us **3 possible aliases**. We try them in order and check availability; the first one that's available becomes your sending address. Aliases aren't guaranteed — if your top choice is taken, we use the next. *** ## Ban & replacement policy If a line does get banned, here's exactly what happens — no other guarantees apply: | Ban | What happens | | - | - | | **1st ban** | We replace the number or iCloud email once, free. | | **2nd & 3rd ban** | \$50 one-time replacement fee each. | | **4th ban** | We can no longer serve that account. | *** ## What we need from you to set up an account > [!TIP] > > A first name, last name, and a real profile picture for **each account** — use the salesperson who will actually handle those conversations. Then we configure an Apple ID email that gives the best shot at a free unban if anyone ever reports you. That setup is only as strong as the identity behind it, which is why the real-name and real-photo rule comes first. # Workspace API Tools Source: https://docs.tuco.ai/features/api-tools Workspace API Tools are saved HTTP requests Tuco calls while building a message, so live data from your backend fills message variables. ## What API Tools Are Workspace API Tools are saved HTTP requests that Tuco can call when it builds a message. Use them to **personalize messages** — pull data from your backend into message variables. ## Creating an API Tool 1. Go to **Integrations → API Tools** 2. Click **+ Add Tool** 3. Configure: * **Name** — e.g. "Check DNC Status" (becomes variable `{api_check_dnc_status}`) * **Method** — GET, POST, PUT, PATCH, DELETE * **URL** — supports lead variables: `https://api.example.com/check/{phone}` * **Headers** — authorization, content-type, etc. * **Body** — JSON request body (with validator and format button) * **Response mapping** — dot-path to extract from response (e.g. `data.status`) 4. **Test** with a real lead to verify it works 5. **Save** ## URL Variables Use lead data in the URL or request body: | Variable | Description | | - | - | | `{phone}` | Lead's phone number | | `{email}` | Lead's email | | `{firstName}` | Lead's first name | | `{lastName}` | Lead's last name | | `{companyName}` | Lead's company name | ## Response Mapping The dot-path tells Tuco which value to extract from the JSON response: | API Response | Response Mapping | Extracted Value | | - | - | - | | `{"data":{"status":"active"}}` | `data.status` | `active` | | `{"verified": true}` | `verified` | `true` | | `{"items":[{"id":1}]}` | `items[0].id` | `1` | ## Using in Messages ``` Hey {firstName}, your account status is {api_check_status|active} ``` ## Important Notes * API tools are **workspace-level** — all team members can use them * Calls are made **in real-time** when the message is built * Test tools before using them in live sends # Calling & Add-ons Source: https://docs.tuco.ai/features/calling-add-ons What calling every phone line includes, the FaceTime Audio and Registered caller ID add-ons, and how add-ons paid at checkout reach each new line. **Every phone line can make and receive calls. Two optional add-ons stop the "Potential spam" label some people see when you call. If you pick an add-on at checkout, it's already paid for: each phone line you order after that gets it automatically, with no new charge.** ## What every phone line includes * **500 outgoing minutes per line per month**, with call recording. Minutes are shared across your phone lines. * **Unlimited incoming calls**, free, forwarded to the number you choose. That number must be in the same country as the line's eSIM. * **Extra minutes:** 100 for \$3. A regular call can show **"Potential spam"** until the person saves your number or taps "Mark as known". Text them first, then call. To learn why, see [Limits: Calling](/limits#calling). ## The two add-ons Add-ons are chosen **per line**. | Add-on | Price | What it does | | - | - | - | | **FaceTime Audio** | \$100/mo per line | Calls go over FaceTime Audio from the same Apple identity that texts the lead, so there's no carrier "Potential spam" label. It costs more because it needs different hardware on our side than iMessage does. | | **Registered caller ID** | $50 setup + $50/mo per line + \$0.075 per call | We give the line a separate calling number and register it with carriers, so your calls show your business name. Calls come from that number, not your texting number. No FaceTime Audio needed. | Registered caller ID shows your name on US-to-US calls to mobiles on T-Mobile and Verizon. Carriers check your business first, so it can take a few business days to go live. You give us your business details in a short form. See [Registered caller ID setup](/features/registered-caller-id). > [!WARNING] > > **Add-ons can't be removed after purchase.** Email [support@tuco.ai](mailto:support@tuco.ai) to change one. ## Add-ons you pick at checkout When you tick an add-on at checkout, you buy it for **every phone line in your plan**. It's charged with your plan. After that, **each phone line you order gets one automatically**. You don't tick anything again, and you aren't charged again. ### On the line order page after checkout Right after you pay, you order your lines. If you picked add-ons at checkout, each line shows a green box: > **Included with this line, already paid at checkout** > FaceTime Audio add-on: added to this line automatically. No new charge. If you picked Registered caller ID, this page also shows the **Caller ID details** form. You can fill it in now or later. Your line is ordered either way. ### When you add a line with Provision Line On **Lines → Provision Line**, the **Calling** step shows each add-on you already paid for as ticked and locked, with a **Paid at checkout** badge and a note like this: > You already paid for FaceTime Audio at checkout (1 unused). It's added to this line automatically. No new charge. * The **"Charge me for…"** box only lists add-ons that will really be charged. If everything you picked was paid at checkout, there's no charge box at all. * On the review screen, a paid add-on shows **"(already paid at checkout, no new charge)"**. * If you tick an add-on you didn't pay for at checkout, it's charged like any other add-on. See the next section. ### Adding an add-on to a line you already have 1. Go to **Lines** and click **Calling** on the line. 2. Tick the add-on you want. 3. Tick the box to agree, then click **Add**. What the box says depends on whether you already paid: * **Already paid at checkout.** The card shows **Paid at checkout** and *"You already paid for this at checkout (1 unused). Adding it to this line costs nothing today."* The box reads: *"Add … to this line using a slot I already paid for at checkout. **No new charge.** It renews with my plan."* * **Not paid yet.** The box reads *"Charge me for … on this line"*. We charge the card on file today: the setup fee plus a prorated share of the monthly price. Then it's charged monthly. Non-refundable. Tuco always uses an add-on you already paid for before it charges for a new one. ## What the status on Lines → Calling means | Status | Meaning | | - | - | | **Paid at checkout** | You already paid for this add-on and it isn't on a line yet. Adding it here costs nothing. | | **Awaiting payment** | Your bank wants you to confirm the payment. Click **Pay the invoice to start it →**. The link stops working after about 23 hours. | | **Setting up** | Paid. We're setting it up. | | **Active** | It's on. For Registered caller ID, the screen shows the number your calls go out from. | ## Frequently asked questions > [accordion] I paid for an add-on at checkout. Will I be charged again when I order a line? > > No. Each phone line you order takes one of the add-ons you already paid for, with no new charge. You'll see "Paid at checkout" or "already paid at checkout, no new charge" while you order. > [accordion] How many lines get an add-on I picked at checkout? > > One for every phone line in your plan. If you order more phone lines than that, adding the add-on to the extra line is a new charge, and you'll see the price and a "Charge me for…" box first. > [accordion] Do I need FaceTime Audio to use Registered caller ID? > > No. They are separate add-ons. Registered caller ID gives the line its own registered calling number. > [accordion] Can I remove an add-on? > > Not from the dashboard. Email [support@tuco.ai](mailto:support@tuco.ai) to change one. > [accordion] How is the \$0.075 per call for Registered caller ID billed? > > Each Registered caller ID call is added to your next invoice. ## For developers * [Calling Add-ons API](/api-reference/endpoint/calling-addons): see and add a line's add-ons. * [Calling Add-on Slots](/api-reference/endpoint/calling-addon-slots): how many add-ons you paid for and how many are still unused. * [Caller ID Details API](/api-reference/endpoint/caller-id-profile): send your Registered caller ID business details. # Check iMessage Availability Source: https://docs.tuco.ai/features/check-availability Verify whether a lead's phone or email supports iMessage before you send, so each message routes through the channel that will actually deliver. ## Overview Verify whether a lead's phone number or email supports iMessage before sending messages. The system automatically checks all new leads and provides manual re-check options. > [!NOTE] > > iMessage availability checking helps you send messages through the optimal channel and avoid delivery failures. *** ## Automatic Checking When you upload leads, the system automatically checks availability: **1. Upload Detection** System detects new leads from upload **2. Address Check** Automatically checks **all phone and email addresses** **3. Status Update** Updates lead record with availability status ### Status Indicators | Icon | Status | Description | | - | - | - | | 🔵 | **Available** | Supports iMessage (blue bubble) | | ⚪ | **Unavailable** | Does not support iMessage (SMS/email only) | | 🔄 | **Checking** | Currently verifying | | ⚠️ | **Error** | Check failed - retry available | | ⭕ | **No Active Line** | Configure a line first | *** ## Manual Checking ### Single Lead Check Check availability for individual leads: 1. Navigate to **Leads** page 2. Find the lead in the table 3. Click **Check Availability** button 4. Status updates in real-time > [!TIP] > > Re-check leads periodically as contacts may enable or disable iMessage on their devices. ### Bulk Checking Check multiple leads at once: 1. Select multiple leads using checkboxes 2. Click **Check Availability** (bulk action in toolbar) 3. System checks all selected leads 4. Progress indicator shows completion > [!NOTE] > > Bulk checking is processed sequentially. Large batches may take a few minutes. > Each line can perform up to **70 availability checks per day**. If you have multiple lines, > checks are distributed across them automatically. High-volume checks may experience slight delays. *** ## Quick Send Preview Get instant availability feedback when composing quick messages: **1. Open Quick Send** Navigate to **Leads → Import** and click **Quick Send** **2. Enter Recipient** Type phone number or email address **3. Auto-Check** System automatically checks availability (500ms debounce) **4. View Status** See availability icon next to recipient field ### Status Icons * 🔵 **Blue circle** - iMessage available * ⚪ **Gray circle** - Not available (will send as SMS/email) * ⏳ **Spinner** - Checking... *** ## How It Works Understanding the availability check process: ```mermaid theme={null} graph TD A[Start Check] --> B{Active Line?} B -->|No| C[Return 'No Active Line'] B -->|Yes| D[Get Server URL] D --> E[Check Primary Phone] E --> F{Available?} F -->|Yes| G[Mark Available - Stop] F -->|No| H[Check Primary Email] H --> I{Available?} I -->|Yes| G I -->|No| J[Check Alt Phones] J --> K{Available?} K -->|Yes| G K -->|No| L[Check Alt Emails] L --> M{Available?} M -->|Yes| G M -->|No| N[Mark Unavailable] ``` ### Check Priority The system checks addresses in this order and stops at the first available one: 1. Primary phone 2. Primary email 3. Alternate phone 1 4. Alternate phone 2 5. Alternate phone 3 6. Alternate email 1 7. Alternate email 2 8. Alternate email 3 > [!NOTE] > > Checking stops at the **first available** address to optimize performance. *** ## Requirements Before checking availability, you must have an active line configured: > [!WARNING] > > **Important:** Without an active line, all checks will show "No Active Line" status. ### Setup Required 1. Navigate to **Lines** page 2. Purchase or configure a line 3. Ensure line status is **Active** 4. Line must have a valid **Server URL** > [card] [Configure Lines](/api-reference/lines) > > Learn how to set up and manage your messaging lines *** ## API Reference ### Check Single Lead Check availability for a specific lead by ID. ```bash theme={null} GET /api/leads/check-availability?id={leadId} ``` **Response:** ```json theme={null} { "success": true, "leadId": "507f1f77bcf86cd799439011", "available": true, "status": "available" } ``` *** ### Check Multiple Leads Batch check multiple leads at once. ```bash theme={null} POST /api/leads/check-availability ``` **Request:** ```json theme={null} { "leadIds": [ "507f1f77bcf86cd799439011", "507f1f77bcf86cd799439012", "507f1f77bcf86cd799439013" ] } ``` **Response:** ```json theme={null} { "success": true, "checked": 3, "successful": 3, "errors": 0, "results": [ { "leadId": "507f1f77bcf86cd799439011", "available": true, "status": "available" }, { "leadId": "507f1f77bcf86cd799439012", "available": false, "status": "unavailable" }, { "leadId": "507f1f77bcf86cd799439013", "available": true, "status": "available" } ] } ``` *** ### Check Individual Address Check availability for a phone or email address (Quick Send). ```bash theme={null} POST /api/leads/check-availability ``` **Request:** ```json theme={null} { "address": "+12025551234" } ``` **Response:** ```json theme={null} { "success": true, "available": true, "address": "+12025551234" } ``` ### Error Codes | Code | Description | | - | - | | `400` | No active line configured | | `401` | Unauthorized - invalid or missing token | | `404` | Lead not found | | `500` | Server error - check failed | *** ## API Integrators: Skip Checking, Use Fallback Webhooks > [!WARNING] > > If you're integrating via API (not using the Tuco UI), the **recommended pattern** > is to skip availability checking entirely: > > 1. Call `POST /api/messages` directly > 2. Listen for the `message.fallback` webhook > 3. When you receive `message.fallback`, trigger your SMS/WhatsApp fallback > > This avoids burning your 70/day/line availability quota and is faster (one API call > instead of two). See the [check-availability-rr endpoint](/api-reference/endpoint/check-availability-rr#recommended-pattern-send--fallback-webhook) for code examples. *** ## Availability Checks vs Send Limits > [!NOTE] > > Availability checks and message sends use **separate** daily counters. > Checking a number does **not** reduce your daily send quota, and sending a > message does **not** reduce your availability check quota. | Counter | Scope | Limit | | - | - | - | | **Send quota** | Per line, per day | Configured per line (see Lines page) | | **Availability quota** | Per line, per day | **70 checks/day** (hard cap) | *** ## Best Practices > [accordion] 🔄 Regular Re-checks > > Re-check leads periodically (weekly/monthly) as people change devices and enable/disable iMessage > [accordion] ⚡ Bulk for Efficiency > > Use bulk checking for large lists to save time and ensure all leads are current > [accordion] ✅ Check Before Bulk Sends > > Always verify availability before large sends to maximize deliverability > [accordion] 📊 Monitor Error Rates > > If you see high error rates, verify your line configuration and server URL *** ## Troubleshooting > [accordion] ❌ 'No Active Line' Status > > **Solution:** Configure an active line in Settings → Lines before checking availability. > [accordion] ⚠️ Check Failed Errors > > **Solution:** Verify your server URL is correct and accessible. Check network connectivity. > [accordion] 🔄 Stuck on 'Checking' > > **Solution:** Refresh the page. If issue persists, check your line's server status. # Compliance, Consent & Opt-Outs Source: https://docs.tuco.ai/features/compliance-and-optouts Patterns for respectful, compliant messaging with Tuco AI across iMessage, SMS and email: consent, opt-outs and the Do Not Contact list. Not legal advice. ## Scope & Disclaimer This page provides **implementation patterns**, not legal advice. * You remain responsible for complying with: * Local and international regulations (e.g. GDPR, CAN-SPAM, TCPA, ePrivacy, etc.). * Your own policies and agreements. * Tuco AI provides primitives (leads, fields, messages, webhooks) that you can combine into compliant flows. Always consult your legal counsel for regulatory specifics. *** ## Consent & Audience Management ### Storing Consent In your own systems and in Tuco leads: * Track consent-related attributes, such as: * `hasConsentedToMessaging` * `consentSource` (e.g. web form, signed contract) * `consentTimestamp` You can: * Store these as: * Custom fields on leads. * Additional metadata in your own database. ### Using Consent in Your Sending Logic Before sending messages: * Filter audiences based on: * Consent flags. * Channels allowed (e.g. iMessage vs email vs SMS). * Regions and applicable regulatory regimes. In your own backend: ```pseudo theme={null} eligibleLeads = leads.filter( lead.hasConsentedToMessaging && lead.prefersImessageOrSms && !lead.isOptedOut ) ``` Tuco then receives: * Only leads you have determined are compliant to contact. *** ## Opt-Out Handling Patterns ### Storing Opt-Out Flags For each lead and channel: * Maintain flags like: * `optedOutOfAll` * `optedOutOfImessage` * `optedOutOfSms` * `optedOutOfEmail` These flags can live primarily in your own systems and be mirrored to Tuco via: * Lead updates. * Custom fields. ### Detecting Opt-Outs from Replies When using replies to capture opt-outs: * Implement logic in your own systems to detect: * Messages containing patterns like: * “STOP”, “UNSUBSCRIBE”, “REMOVE ME” (case-insensitive, language-sensitive). * Domain-specific phrases for your regions. Flow: 1. Tuco ingests replies and surfaces them via: * The app’s inbox / UI. * Message or reply webhooks. 2. Your webhook consumer: * Classifies replies. * Updates: * `optedOutOfX` flags for the lead. 3. Future sending logic: * Excludes leads with opt-out flags for the relevant channels. ### Manual Opt-Outs Provide administrative tools (in your own product and/or in Tuco) to: * Manually set or clear opt-out flags. * View opt-out history per lead. *** ## Channel-Specific Considerations ### iMessage / SMS Regulations often require: * Clear identification of the sender. * Clear instructions for opting out, especially for SMS. Patterns: * Include: * Your brand name. * Simple opt-out wording (e.g. “Reply STOP to unsubscribe” where appropriate). * Ensure replies that represent opt-outs: * Are processed quickly. * Immediately stop further outreach on that channel. ### Email Common requirements (varies by jurisdiction): * Unsubscribe link or mechanism in every email. * Valid physical mailing address. * Accurate “From” fields and subject lines. Tuco can: * Deliver email content as you design it. * Track message states and replies. You are responsible for: * Including regulatory-required content in templates. * Maintaining suppression lists for opted-out addresses. *** ## Suppression & Exclusion Lists Even with consent and opt-outs tracked per lead, you may want: * **Global suppression lists**: * Domains or addresses never to contact (e.g. internal test emails, role accounts). * **Segment-level exclusions**: * Don’t message leads included in another specific segment. Patterns: * Maintain suppression lists in your own system. * Filter before sending messages via Tuco. *** ## Auditing & Record-Keeping For compliance and internal governance, maintain: * **Event history** per lead: * When consent was granted and from where. * When opt-outs were received and processed. * Messages sent. * **System logs**: * Who in your organization modified consent or opt-out fields. * Changes to template content and targeting rules. Tuco’s message and webhook data can help: * Provide evidence of what was sent and when. * Correlate with your own consent and opt-out records. *** ## Governance & Review Processes For enterprise deployments: * Establish review processes for: * New templates (tone, content, compliance). * New segments and targeting logic. * Changes to consent and opt-out handling logic. * Involve: * Legal/compliance teams. * Data protection officers (where required). *** ## Summary Tuco AI provides the infrastructure to: * Send messages via multiple channels. * Track deliveries and replies. * Integrate with your systems via APIs and webhooks. Compliance depends on how you: * Collect and store consent. * Implement opt-out and suppression logic. * Design and review your templates and outreach. By combining Tuco’s primitives with the patterns on this page and professional legal advice, you can run large-scale, compliant outreach programs without exposing or depending on internal Tuco APIs. # Do Not Contact (DNC) Source: https://docs.tuco.ai/features/dnc Tuco's Do Not Contact list blocks sends to excluded phones and emails, with manual entries, automatic opt-out detection and pre-send blocking. The DNC system prevents messages from being sent to excluded contacts. It includes manual management, automatic opt-out detection, and pre-send blocking. ## Features * **Manual add/remove** via UI or API * **Auto opt-out**: Replies containing STOP, UNSUBSCRIBE, OPT OUT, REMOVE ME, or DO NOT CONTACT are automatically added. Carrier keywords (STOP, STOPALL, UNSUBSCRIBE, CANCEL, END, QUIT) sent to your Telnyx or Twilio fallback number are added too * **`dnc.added` webhook** and **`GET /api/dnc?since=`** so you can stop the same contact on your other channels * **Pre-send blocking**: Every message is checked against DNC before sending * **E.164 normalization**: Phone numbers are normalized for consistent matching ## UI Navigate to `/dnc` (shield icon in sidebar): * Search and filter DNC entries * Add by phone or email * Remove entries * Paginated table view ## API Full reference: [List / check](/api-reference/endpoint/list-dnc) · [Add](/api-reference/endpoint/add-dnc) · [Bulk add](/api-reference/endpoint/bulk-add-dnc) · [`dnc.added` webhook](/api-reference/message-webhooks#dnc-added). `GET`, `POST` and `PATCH` (bulk add, up to 10,000) accept a workspace API key (`Authorization: Bearer tuco_…`) or a dashboard session. Removing an entry, and importing from a Tuco list or tag, are dashboard-only. ### List DNC entries ```bash theme={null} curl "https://app.tuco.ai/api/dnc?page=1&limit=50" \ -H "Authorization: Bearer tuco_YOUR_KEY" ``` ```json theme={null} { "entries": [ { "id": "6713b1c2e4b0a1d2c3f40001", "phone": "+19045551234", "email": null, "reason": "opt-out", "addedBy": "system", "addedAt": "2026-10-19T11:22:49.693Z", "source": "keyword-STOP" } ], "total": 1, "page": 1, "limit": 50, "totalPages": 1, "hasMore": false } ``` | Query | | | - | - | | `page`, `limit` | Paging. `limit` is at most 200 (default 50). | | `since` | ISO 8601 date. Only entries added at or after it, **oldest first**. | | `phone` / `email` | Check one contact. Adds `listed: true \| false` to the response. | | `search` | Substring match on phone or email. | Without `since`, entries are newest first. `source` tells you how the entry got there: `keyword-STOP` (or another keyword) for an opt-out reply, `api` for `POST /api/dnc` with an API key, `api-bulk` for `PATCH /api/dnc`, `manual-ui` for the dashboard, `csv-import` / `list-import` / `tag-import` for bulk imports, and the CRM name for GoHighLevel and HubSpot syncs. ### Poll for new opt-outs Store the `addedAt` of the last entry you processed and pass it as `since`: ```bash theme={null} curl "https://app.tuco.ai/api/dnc?since=2026-10-19T11:22:49.693Z&limit=200" \ -H "Authorization: Bearer tuco_YOUR_KEY" ``` `since` is inclusive, so the last entry you saw comes back again. Dedupe by `id`. When `hasMore` is `true`, read the next `page`. To hear about opt-outs immediately instead of polling, subscribe to the [`dnc.added` webhook](/api-reference/message-webhooks#dnc-added). ### Check one number ```bash theme={null} curl "https://app.tuco.ai/api/dnc?phone=%2B19045551234" \ -H "Authorization: Bearer tuco_YOUR_KEY" ``` `listed` is `true` if the number is on the list. The number can be in any common format; `+` must be URL-encoded as `%2B`. ### Add to DNC ```bash theme={null} curl -X POST "https://app.tuco.ai/api/dnc" \ -H "Authorization: Bearer tuco_YOUR_KEY" \ -H "Content-Type: application/json" \ -d '{ "phone": "(904) 555-1234", "reason": "whatsapp-opt-out" }' ``` The phone is stored in E.164 (`+19045551234`). Returns `{ "ok": true, "id": "…" }`, or `409` if the contact is already on the list. A successful add fires `dnc.added`. ### Remove from DNC Dashboard only: ```bash theme={null} DELETE /api/dnc?id=507f1f77bcf86cd799439011 ``` API keys are rate limited to 120 requests per minute per workspace (`429` with `Retry-After`). ## Debugging Blocked sends are recorded internally. Review a contact’s DNC status and blocked-send history from the **Leads** view or the API. # Email Bridge Source: https://docs.tuco.ai/features/email-bridge Send iMessages by emailing +phone@send.tuco.ai from Gmail, Outlook or any email client. No app or API needed; Tuco emails you a confirmation. ## How Email Bridge Works Send iMessages by emailing `+phone@send.tuco.ai` from your email client. No app, no API, no setup beyond having a Tuco account. ## Sending a Message 1. Compose an email in Gmail, Outlook, or any email client 2. Set the **To** field to: `+19045551234@send.tuco.ai` 3. Write your message in the email body 4. Hit Send — Tuco sends it as an iMessage and emails you a confirmation ## Email Formats | Format | Description | | - | - | | `+19045551234@send.tuco.ai` | Uses your first available active line | | `+19045551234-1@send.tuco.ai` | Uses a specific line number (shown on Lines page) | ## Requirements * Your email must be registered in Tuco (or added to the sender allowlist) * Your workspace must have at least one active iMessage line * Phone number must be in E.164 format (+country code + number) ## Sender Allowlist Allow additional email addresses to send via the bridge without a Tuco account: 1. Go to **Integrations → Email Bridge** 2. Add colleague emails to the allowlist 3. They can now send iMessages via email ## Error Handling If something goes wrong, you receive a bounce email: | Error | Fix | | - | - | | Invalid phone number | Check format: +19045551234 | | Not authorized | Your email isn't registered or allowlisted | | No active lines | Set up a line at Lines → Purchase | | Send failed | Recipient may not have iMessage | # Export All Data (CSV) Source: https://docs.tuco.ai/features/export-data Download your Unibox conversations and activity log as CSV files — sent messages, replies, reactions, voice notes, calls, and system events. ## What You Can Export Tuco lets you download your workspace data as CSV files directly from the app — no API keys or scripts required. Two exports are available: * **Unibox conversations** — every sent and received message, grouped by contact so each conversation reads top to bottom like your Unibox thread. * **Activity log events** — system events such as sends, deliveries, failures, fallbacks, CRM syncs, and webhooks. Both open cleanly in Excel, Google Sheets, or any BI tool. *** ## How to Export 1. Open **Activity Log** in your Tuco workspace. 2. Click the **Export All Data** button (bottom-right corner — it stays visible while you scroll). 3. Choose what to include: * **Unibox conversations**, **Activity log events**, or both. * For activity events, pick the categories you want (Messages, Replies, Webhooks, CRM syncs, Telegram, System, Voice calls). 4. Pick a date range — last 24 hours, 7 days, 30 days, or all time. 5. Click **Export CSV**. One CSV file downloads per selected dataset. > [!NOTE] > > Exports are scoped to your current workspace and respect your role's access. Very large workspaces are capped at 50,000 rows per file — narrow the date range to segment bigger histories. *** ## What's Inside the Conversations CSV Each row is one item in a conversation, in thread order: | Column | Meaning | | - | - | | Conversation | The contact the thread belongs to | | Date / Direction | When it happened and whether you sent or received it | | Kind | `message`, `reaction`, `voice note`, or `call` | | Channel | iMessage, SMS, email, or call | | Status | sent, delivered, failed, fallback, etc. | | Message | The full text body | | Reactions | Tapbacks the contact left on your messages (e.g. ❤️ Loved) | | Attachments | File names of photos, videos, and voice notes | | Call Duration / Answered | For call entries, how long and whether it connected | | Sent At / Delivered At / Read At | Delivery timeline timestamps | Inbound reactions (Loved, Liked, Laughed at…), inbound voice notes, and placed calls all appear as their own rows with the `Kind` column set accordingly, so reply-rate math in your spreadsheet can include or exclude them explicitly. *** ## What's Inside the Activity Log CSV Each row is one system event: the event type (for example `message_sent`, `reply_received`, `message_fallback`), its status, description, the contact and line involved, the source that triggered it (dashboard, API, CRM), and error details when something failed. This is the same data you see on the Activity Log page, so anything you can filter there you can also take with you. *** ## Related * [Replies & Inbox](/features/replies) — how replies are captured and matched. * [Reactions](/features/reactions) — how tapbacks behave. * [Export & Data Integration](/analytics/export-strategies) — moving Tuco data into BI and reporting tools on an ongoing basis. # Failures, Fallbacks & Delivery Outcomes Source: https://docs.tuco.ai/features/failures-and-fallbacks What can happen to a Tuco message at scale (sent, delivered, failed, fallback to SMS or email) and how to react to each outcome in your own systems. ## Why Delivery Outcomes Matter When you send messages at scale, not every attempt will succeed: * Some addresses are invalid or no longer in use. * Some recipients don’t support iMessage. * Some channels are temporarily unavailable. Tuco is designed so that, from your point of view: * Every message ends up in a **clear, stable outcome state**. * You can safely build automations that respond to those states. * You do **not** need to understand the underlying retry or routing logic. This page focuses purely on the **outcomes you see** and how to use them. *** ## Message Statuses You Can Build On Across the app, APIs, and webhooks, you’ll see a small set of message statuses: * **queued** * The message is planned, but not yet eligible to send. * Common reasons: * Waiting for allowed hours or days. * Waiting for free capacity on a line. * Use this to monitor future workload and expected sends. * **pending / sending** * The message is in the process of being sent. * Use this to distinguish “actively in flight” from “just planned”. * **sent** * Tuco successfully handed the message to the downstream channel (e.g. iMessage, SMS, email) according to that channel’s contract. * Use this to: * Trigger internal workflows (“message was sent”). * Update activity feeds or timelines. * **delivered** (where supported) * Tuco received a confirmation that the message reached the recipient’s device or mailbox. * Not all channels support this; when they do, Tuco surfaces it clearly. * Use this to: * Measure true delivery rates. * Trigger time‑based follow‑ups (“sent and delivered, now wait X days”). * **failed** * Tuco determined that this message **cannot** be sent. * Typical reasons include: * Permanently invalid address. * Hard rejection from the underlying channel. * Configuration that makes the send impossible. * Failed messages are not silently retried. * Use this to: * Flag data for cleanup. * Alert operators for high failure rates on a line. * **fallback** * The primary channel you wanted to use isn’t available for this recipient (for example, no iMessage‑capable address), or sending on that path is not safe. * Tuco: * Marks the message as `fallback`. * Emits a clear event (see `/api-reference/message-webhooks`). * Use this to: * Switch to SMS or email, if appropriate. * Tag leads as “not reachable on iMessage”. *** ## What Tuco Does vs What You Decide Tuco handles: * Running availability checks behind the scenes. * Respecting your time windows, day‑of‑week rules, and line limits. * Deciding when to treat an error as final vs something that can be retried internally. You handle: * **Business decisions** when you see `failed` or `fallback`: * Whether to try another channel. * Whether to mark a lead as needing attention. * Whether to treat repeated failures as a sign to stop contacting a segment. * **Data hygiene**: * Cleaning invalid numbers or emails. * Updating lead records after repeated failures. * **Customer experience**: * Avoiding aggressive retries in your own systems. * Respecting consent and preferences when switching channels. This separation lets you rely on Tuco’s guardrails while still owning your customer‑facing behavior. *** ## Typical Failure & Fallback Scenarios ### 1. Invalid or Out‑of‑Date Contact Info **What happens:** * You send to a phone or email that is no longer valid. * The underlying channel rejects the message. * Tuco marks the message as **failed** and surfaces a clear reason in the UI and/or API. **How to react:** * Suppress or clean the offending address in your own systems. * Consider updating your import or validation flows to catch these earlier. * Watch for patterns (e.g. a particular list or source producing many invalid contacts). *** ### 2. Recipient Does Not Support iMessage **What happens:** * Tuco determines that none of the stored addresses for a lead support iMessage. * The iMessage path is not used. * The message is marked as **fallback**, and a webhook event is emitted if configured. **How to react:** * Route follow‑up via your preferred alternative: * SMS for time‑sensitive notifications. * Email for longer‑form communication. * Tag the lead in your CRM as “no iMessage” so future outreach uses appropriate channels. * Use `/features/check-availability` to periodically refresh availability and keep this accurate. *** ### 3. Limits, Time Windows, and Gaps **What happens:** * A message cannot be sent **right now** because: * Daily limits on a line have been reached. * You’re outside allowed hours or days. * Your pacing rules between contacts on a line are still in effect. * Tuco leaves the message as **queued** and checks again later. **How to react:** * Treat **Queued** as “not attempted yet”, not as a failure. * If many messages stay queued for long periods: * Add capacity by configuring more lines. * Relax your timing windows, if consistent with your brand and compliance. * Re‑evaluate how much outreach you run in parallel on the same lines. *** ### 4. Sustained Problems on a Channel or Line **What happens:** * A line or channel experiences longer‑lasting issues. * Tuco protects recipients and your account by: * Reducing or pausing sends on that path. * Exposing more **failed**, **queued**, or **fallback** outcomes instead of forcing traffic through. **How to react:** * Use line‑level stats to: * Spot unusually high **failed** or **fallback** rates. * Identify which lines are affected. * Temporarily: * Shift traffic to healthier channels or lines. * Pause the affected sends or workflows while you investigate. You do **not** need to manage any recovery mechanics in Tuco itself—just respond to the visible outcomes. *** ## Using Outcomes in Your Own Systems You can consume delivery outcomes through: * The Tuco UI (for operational teams). * The API responses and list endpoints. * **Message webhooks** (see `/api-reference/message-webhooks`) for real‑time integration. Common patterns teams implement: * **CRM updates** * Mark a contact as “Reached”, “Bounced”, or “Fallback to SMS” based on final status. * Record last successful contact date vs last attempt date. * **Automated follow‑ups** * Start a different sequence when a message fails. * Trigger a task for a human when a VIP contact hits repeated failures. * **Health dashboards** * Track ratios of `sent` / `delivered` / `failed` / `fallback` per line or segment. * Alert internally when failures or fallbacks cross a threshold. All of this can be done using only the **public surfaces** Tuco exposes—no need to depend on worker internals or implementation details. *** ## Send SMS via GoHighLevel (GHL) as fallback When you receive a **`message.fallback`** webhook (recipient has no iMessage), you can send the same content as SMS using **GoHighLevel LeadConnector**. This keeps the conversation in one place in GHL. **Webhook payload you receive** (relevant fields): * `body.leadId`, `body.ghlContactId`, `body.ghlLocationId` * `body.message` — for fallback the **message object** is in `body.message`; use `body.message.message` for the text, or `body.data.reason` for context. * For **outbound** fallback (you tried to send iMessage, it failed): `body.message` is the full message document; `body.message.message` is the text to send via SMS. **GHL API call (LeadConnector):** ```http theme={null} POST https://services.leadconnectorhq.com/conversations/messages Authorization: Bearer Version: 2021-07-28 Content-Type: application/json ``` **Body (form or JSON per GHL docs):** | Field | Value | | - | - | | `locationId` | `body.ghlLocationId` from webhook | | `contactId` | `body.ghlContactId` from webhook | | `message` | Text to send (e.g. `body.message.message` or the original message text) | | `type` | `SMS` | | `lastMessageDate` | Current time (e.g. `Date.now()`) | Example (n8n / automation): when the **Failed & Fallback** webhook fires, read `ghlContactId`, `ghlLocationId`, and the message text from the webhook body, then POST to LeadConnector’s `conversations/messages` with `type: "SMS"`. The conversation will appear in GHL as SMS. > [!NOTE] > > Tuco can also send **fallback SMS via Twilio** automatically when you enable **sendFallbackSmsOnFailed** and configure Twilio in workspace settings. The GHL approach above is for teams who want fallback to go through GoHighLevel instead. *** ## Best Practices * **Focus on trends, not one‑offs** * Individual failures are normal. * Spikes in `failed` or `fallback` rates are what deserve attention. * **Use fallbacks thoughtfully** * Treat `fallback` as a chance to choose the channel that best fits the moment. * Avoid automatically “spamming in every channel” after a single fallback event. * **Keep data clean** * Clean or suppress addresses that repeatedly fail. * Feed learnings back into your imports and validation rules. * **Respect consent** * Before reacting to a failure or fallback with another channel, ensure your consent and opt‑out rules allow it. * See `/features/compliance-and-optouts` for patterns. Handled this way, Tuco’s outcomes give you **clear, actionable signals** without revealing how the underlying infrastructure works—and allow you to design robust, customer‑friendly journeys on top. # Goal Bots Source: https://docs.tuco.ai/features/goal-bots One prompt, the tools it may use, and the tags that fire it. A goal bot answers when a tagged lead replies and can book a real appointment on a real calendar. A goal bot is three things: 1. **A prompt** — the whole job, in plain English 2. **Tools** — exactly what it is allowed to do 3. **Tags** — which leads it answers When a lead carrying one of its tags replies, the bot reads the conversation, decides what to say, calls whatever tools it needs, and answers. One bot runs the whole conversation: it qualifies **and** books. There is no handoff to a second bot. > [!NOTE] > > Goal bots used to be built from **stages** — step 1, step 2, step 3, each with its > own advance conditions. Stages are gone. The conversation itself is the state: the > bot reads the thread and knows what it has already asked, so there is no step > pointer to get stuck or jump ahead. ## Writing the prompt Write it the way you would brief a new rep. Ordered instructions are fine — the bot follows them without needing a stage machine. ``` Find out how many jobs a week they could handle and whether they can service same or next day. If they can do 5+ a week and same or next day, offer the free trial. Check the calendar, offer two real times, and book the one they pick. If they cannot, warmly say we are not a fit and add the tag nurture. ``` Things worth putting in the prompt: answer a direct question before carrying on, reply in the language the lead is writing in, and drop a question after asking it twice rather than looping. ## Tools A bot can only use what you give it, so it can never talk about doing something it cannot do. | tool | what it does | | - | - | | `get_lead_details` | name, email, company, timezone, tags, custom fields and the lead's notes already on file | | `convert_timezone` | always available | | `ghl_check_slots` / `ghl_book_appointment` | GoHighLevel calendar | | `check_calendly_slots` / `book_calendly_meeting` | Calendly | | `ghl_add_tag` / `ghl_remove_tag` | tag the contact as the conversation moves | Only one calendar's booking tools are ever handed to a bot, so it cannot book into the wrong calendar when both are connected. > [!NOTE] > > `get_lead_details` is how the bot picks up context your team already has. Whatever is in a > lead's **Notes** — "quoted in March, went quiet", "only answers after 5pm" — comes back with > it, so the bot works from it instead of asking the lead something you already know. Notes are > treated as internal: the bot uses them for context and does not read them back to the lead. ## Tags decide who it talks to `includeTags` is the trigger. The bot answers a lead carrying any one of them. `excludeTags` is the veto — it never answers a lead carrying one of those. > [!WARNING] > > Tags are matched **exactly** and are case sensitive. A bot pointed at a tag your > CRM workflow never actually applies will never fire for anyone, and it fails > silently — the lead replies and nothing happens. Check the tag exists on real > leads in your CRM, not just in the bot. > > An **empty** `includeTags` means every lead who replies. The oldest active bot > with no tag filter answers every conversation before any other bot sees it. A common pattern is to tag on completion: `onDoneTag` is applied to the lead once the bot books, which your CRM workflow can pick up. ## Reply hours — when it is allowed to answer Each bot has its **own** hours: pick the days it answers, and a start and end time for each. Outside them the bot sends nothing and a person answers instead. You set it on the bot's own page, under **Reply time settings**. **A bot with no hours answers at all times.** That is how every bot starts, so setting hours is the only thing that can make a bot quieter. ### What happens outside the hours The bot sends nothing and drafts nothing — but **you still get told**. The ordinary new-reply email and Telegram arrive, exactly as they would for a workspace with no bot at all. No empty draft, no "AI needs help" alert. Only the bot's work stops. > [!WARNING] > > **Nothing is queued.** A message that arrives outside the hours is not answered > later when the window reopens. There is no catch-up. From that point the > conversation is yours to answer by hand. ### The override One switch, three positions: | | | | - | - | | **No override** | follow the days and times you set | | **Always answer** | answer whatever the day and time say | | **Never answer** | stay silent, even inside the window | An override does **not** erase your schedule. Clear it and your saved days come back. It has **no expiry** — one set on a Friday is still set on Monday. ### Night shifts Set an end time **earlier** than the start and the window runs past midnight. `20:00` to `08:00` on Monday means Monday evening through **Tuesday 08:00** — the hours belong to the day the shift starts. For a bot that answers all night, every night, set the shift on each day it begins: Monday to Friday at 20:00–08:00 answers from Monday night through Saturday morning, and stays quiet in the daytime gap between shifts. ### Worth knowing * The times use your **workspace timezone**, not the lead's and not ours. Daylight saving is handled, so 09:00 stays 09:00 across a clock change. * The **end time is exclusive**: 09:00–17:00 answers at 16:59 and not at 17:00. * There is **no workspace-wide schedule**. Hours are per bot, so your booking bot can run late while an outreach bot stops at five. > [!WARNING] > > Hours apply to the bot that **answers**, which is not always the one you set > them on. Routing happens first. A bot with an empty `includeTags` answers every > lead before the default **Auto Replies** bot does — so hours on the default bot > do nothing if you also have an untagged bot. Check which bot actually answers a > lead before you schedule it. You can also read and set this over the API — see [Reply Hours](/api-reference/endpoint/reply-hours). ## Two things the engine enforces on its own These hold no matter what the prompt says. **It cannot book a time the lead was never offered.** A booking is refused unless an earlier bot message actually named a clock time. A "yes" to the trial is not a "yes" to a time — the bot has to offer, and the lead has to pick. **It cannot book a time the calendar did not return.** The requested slot is re-checked against live availability before booking; on a miss the bot is handed the real nearest times so it re-offers instead of inventing one. ## Saving what the bot learns A bot can write the answers it gets straight onto the lead. List what you want under `collectFields`: ```json theme={null} { "collectFields": ["goal", "lead_source", "spam_issue", "current_tool"] } ``` Nothing goes in the prompt and there is no tool to call. After each reply the bot reads the conversation and saves whatever it now knows onto the lead's `customFields`, in the lead's own words: ``` goal lead reactivation lead_source instagram and google ads spam_issue no trouble with sms so far current_tool none yet, first time with imessage ``` They show on the lead page and in the inbox, next to the fields your CRM imported. Nothing new to set up. A field they have not answered yet is left empty rather than guessed, and fills in later as the conversation goes on. An earlier answer is never overwritten with a blank. Leave `collectFields` out and nothing is extracted. ## Typing indicator Bots show the typing indicator before replying, because a tool loop makes real calls and checking a calendar can take a few seconds. Turn it off for a particular bot with `"typingIndicator": false`. It only works on lines where the Private API is available. Everywhere else it is skipped regardless of the setting. ## Testing before you go live Create the bot with `"status": "paused"`, then use [Simulate](/api-reference/endpoint/simulate-goal-bot) to run it against a transcript. Nothing is sent — no message, no draft, no notification — and the response shows which tools actually ran, so a bot that only *talks about* checking a calendar is obvious straight away. When it reads right, `PATCH` it to `active`. > [!WARNING] > > A goal bot outranks the knowledge-base reply bot. When one matches a lead, it owns > the reply and the KB bot is skipped, including when the KB bot is in manual mode. ## API Goal bots are fully manageable with a workspace API key — prompt, tools, tags, tone, and status. See [List Goal Bots](/api-reference/endpoint/list-goal-bots) to get started. `/api/goal-bots` and `/api/tasks` are the same API. `/api/tasks` is the name from before the engines merged and still works; responses carry both `goalBots` and `taskAgents` keys. # Knowledge Base Source: https://docs.tuco.ai/features/knowledge-base Tuco's Knowledge Base (now under AI SDR → Knowledge) is the AI reply engine: when a lead replies, it drafts or sends answers from your sources. > [!NOTE] > > The Knowledge Base is now part of **AI SDR** — find it at AI SDR → Knowledge tab. ## What the Knowledge Base Does The Knowledge Base (KB) is Tuco's AI reply engine. When a lead replies to your message, the KB can: * **Draft a reply** using your business context, FAQs, and conversation history * **Send automatically** (Autopilot) or **wait for approval** (Copilot) * **Route to the right person** via Telegram and email notifications ## Modes ### Manual No AI involvement. Replies are forwarded to the contact owner via Telegram and email. You reply manually from Unibox. ### Copilot AI drafts a reply and sends it to the contact owner for approval: * Telegram notification with **Approve** / **Reject** buttons * Email with the draft and approval link * The draft appears in Unibox for editing before sending ### Autopilot AI sends the reply automatically without human approval. Use for high-volume, low-risk conversations. ## How It Works 1. Lead replies → message is debounced (60 seconds of silence) 2. All messages in the batch are combined 3. KB generates a contextual reply using your uploaded knowledge 4. **Copilot**: draft sent to owner for approval via Telegram + email 5. **Autopilot**: reply sent immediately, notification sent to owner ## Notifications The contact owner receives notifications via: * **Telegram** (personal channel if linked, workspace channel as fallback) * **Email** (contact owner's email, with [support@tuco.ai](mailto:support@tuco.ai) CC'd) If the contact owner can't be found, notifications go to the earliest workspace member. ## Daily Limits Set a max auto-replies per day limit in **Integrations → Telegram → Auto-Reply Limits** (default: 50, max: 500). Once reached, new replies wait until the next day. ## Multi-Bubble Replies The AI Responder sends replies as multiple short iMessage bubbles instead of one long message. This looks more natural: * Replies split into 2-4 short messages * Typing indicator ("...") appears between each bubble * 1-3 second delay between bubbles (based on message length) * All gaps and throttles bypassed for AI replies — leads don't wait 30 seconds between bubbles ## Reactions The AI Responder detects iMessage reactions (tapbacks) and does NOT treat them as messages: * Heart, thumbs up/down, laugh, emphasize, question, and custom emoji reactions are recognized * No AI call is wasted on reactions * No notifications sent for reactions ## Voice Notes When a lead sends a voice note: * Audio file is downloaded and stored * Displayed as an audio player in Unibox * Optional: transcribe via Whisper AI (enable in workspace settings) * Transcription passed to AI Responder as the inbound message ## Goal Bot Integration When a goal bot matches a lead, it owns the reply and the knowledge base responder is skipped — including when the KB bot is in manual mode. A goal bot answers from its own prompt, not from knowledge base search. See [Goal Bots](/features/goal-bots) for details. # Language Audit Source: https://docs.tuco.ai/features/language-audit Control the exact words and phrases Tuco's AI can use in outbound messages — block banned terms and keep every automated reply on-brand. Configure allowed and blocked phrases for your workspace. The AI will avoid blocked phrases and prefer allowed phrases when generating messages. ## API ### Get Language Config ```bash cURL theme={null} curl -X GET https://app.tuco.ai/api/language-audit \ -H "Authorization: Bearer YOUR_API_KEY" ``` **Response:** ```json theme={null} { "allowedPhrases": ["custom build", "adventure-ready", "van life"], "blockedPhrases": ["cheap", "discount", "deal"], "customInstructions": "Always use brand voice: enthusiastic but professional." } ``` ### Update Language Config ```bash cURL theme={null} curl -X POST https://app.tuco.ai/api/language-audit \ -H "Authorization: Bearer YOUR_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "allowedPhrases": ["custom build", "adventure-ready"], "blockedPhrases": ["cheap", "deal"], "customInstructions": "Use words from actual customer calls." }' ``` ## How It Works 1. Add phrases from your actual customer calls, ads, and reviews 2. Block generic AI-sounding words ("leverage", "synergy", "utilize") 3. Tuco's AI references these when generating content 4. Custom instructions are injected into the AI system prompt ## Best Practices * Pull words from Fathom call transcripts * Review ad copy for brand-consistent language * Update quarterly as your messaging evolves # MCP Server Source: https://docs.tuco.ai/features/mcp-server Connect Claude, Cursor, Windsurf, and any MCP client to your Tuco workspace. Send iMessages, reply to leads, and read analytics via the authed API. ## What is the Tuco MCP Server? The Model Context Protocol (MCP) server lets AI assistants drive your Tuco workspace using natural language. Every tool call hits the same authenticated REST API as the Tuco dashboard, so anything an MCP client does is auditable in the activity log and visible in [/analytics](https://app.tuco.ai/analytics). Works with Claude Desktop, Cursor, Windsurf, and any MCP-compatible client. ## Installation ```bash theme={null} npx tuco-mcp ``` Package: [`tuco-mcp` on npm](https://www.npmjs.com/package/tuco-mcp). Tools across messaging, the unified inbox, replies, leads, lines, and analytics. ## Configuration Add to your Claude Desktop config (`claude_desktop_config.json`): ```json theme={null} { "mcpServers": { "tuco": { "command": "npx", "args": ["tuco-mcp"], "env": { "TUCO_API_KEY": "tuco_your_api_key" } } } } ``` Get your API key from **[Integrations → API Keys](https://app.tuco.ai/integrations)** in the dashboard. ### Environment variables | Variable | Required | Default | Description | | - | - | - | - | | `TUCO_API_KEY` | Yes | — | Your workspace API key (`tuco_…`). | | `TUCO_API_URL` | No | `https://app.tuco.ai` | API base URL. Override only if Tuco support points you at a different environment. | Equivalent CLI flags: `npx tuco-mcp --api-key tuco_your_api_key --api-url https://app.tuco.ai`. Your key is bound to one workspace **and** one environment, so `TUCO_API_URL` must match the environment the key was issued for. ## Core Tools The tools you'll reach for first: | Tool | What it does | Underlying endpoint | | - | - | - | | `send-imessage` | Send to a phone or email. Scheduling, send window (`sendWindowStart`/`sendWindowEnd`, `timezone`, `allowedDaysOfWeek` 0=Sun…6=Sat), `respectGap`, `skipIfReplied`, attachments, voice notes, SMS fallback. | [`POST /api/messages`](/api-reference/endpoint/send-message) | | `send-batch` | Many messages in one call. Each item needs `message`, `messageType`, `fromLineId` and a phone or email; per-item window in `settings`. | `POST /api/messages/batch` | | `get-replies` | Paginated reply list. Filter by lead, phone, email, **sending line**, and a **UTC date window**. | `GET /api/replies` | | `send-reply` | Reply back in a conversation. Also replies into an iMessage **group**: pass the group's `group:…` id as `conversationId` ([group chats](/api-reference/endpoint/send-group-message)). | `POST /api/unibox/send-reply` | | `suggest-reply` | AI-suggested reply options for a conversation (uses KB if configured). | `POST /api/unibox/suggest-reply` | | `list-conversations` | Filter the unified inbox by status, tag, owner, custom property. Group chats come back with `isGroup: true` and a `group:…` id. | `GET /api/unibox/conversations` | | `analytics` | Reached, sent, SMS fallback, failed, replied, unique repliers, reply %, positive replies, positive %. Filterable by line, user, date window. | `GET /api/analytics` | | `cancel-lead-messages` | Cancel pending/queued/scheduled messages for a lead (e.g. on opt-out). | `POST /api/messages/cancel-for-lead` | | `create-line-request` / `get-line-request` | Order a new line (eSIM number, ported number or email line). `legalFirstName`, `legalLastName`, `companyName`, `antiSpamAccepted: true` and `channelType` are mandatory; an eSIM order also needs `simCountry`, `addressLine1`, `city`, `state`, `legalZipcode`, `zipcode`, `areaCodeBestEffortAcknowledged: true`. `reviewOnly: true` previews without creating; poll by id. | [`POST /api/line-requests`](/api-reference/endpoint/create-line-request) | | `list-dnc` | Do-Not-Contact entries. `since` returns new opt-outs oldest first. | [`GET /api/dnc`](/api-reference/endpoint/list-dnc) | | `check-dnc` | Is this phone or email on the Do-Not-Contact list? (`listed`) | [`GET /api/dnc?phone=`](/api-reference/endpoint/list-dnc) | | `add-to-dnc` | Add one phone or email (fires `dnc.added`). | [`POST /api/dnc`](/api-reference/endpoint/add-dnc) | | `bulk-add-to-dnc` | Add up to 10,000 phones/emails, idempotent. | [`PATCH /api/dnc`](/api-reference/endpoint/bulk-add-dnc) | | `create-webhook` / `update-webhook` | Subscribe a URL to events (incl. `dnc.added`), pause/resume. | [`POST /api/webhooks`](/api-reference/endpoint/create-webhook) | | `send-test-webhook` | Test delivery identical to a live one, per event + variant. | [`POST /api/webhooks/{id}/test`](/api-reference/endpoint/send-test-webhook) | | `list-webhook-deliveries` / `replay-webhook-delivery` | Delivery log with exact request/response; re-send any delivery. | [`GET /api/webhooks/{id}/deliveries`](/api-reference/endpoint/list-webhook-deliveries) | The server exposes 96 tools; any MCP client's tool browser lists them all. ## Example Prompts Reply triage and outreach loop: * "Send an iMessage to +12125551234 saying 'Hey, wanted to follow up'" * "Fetch all replies received on line `` between June 1 and June 10." * "Show reply rate and positive reply rate on line `` over the last 7 days." * "List my last 50 unread conversations, then suggest a reply for the top one." * "Reply 'Thanks, sending a calendar link now' to the conversation with +12125551234." Opt-out sync across channels: * "Who replied STOP since 9am? Give me their numbers so I can remove them from WhatsApp." * "Is +15551234567 on our Do-Not-Contact list?" * "Add these 300 numbers to DNC — they unsubscribed by email." The `get-replies` and `analytics` filters compose, so you can ask things like *"What's the positive reply rate on line X last week, and show me each replier."* ## Reply Pagination & Filters `get-replies` mirrors the API: | Param | Type | Notes | | - | - | - | | `leadId` | string | A single lead. | | `recipientPhone` | string | E.164 or any normalizable format. | | `recipientEmail` | string | Exact match. | | `lineId` | string | Restrict to replies received on this Tuco line. | | `dateFrom` / `dateTo` | ISO 8601 | Inclusive UTC window on the reply timestamp. | | `page` / `limit` | integer | Default `page=1`, `limit=50`, max `100`. | The response includes `total`, `page`, `limit`, `totalPages`, and each row carries `recentReplies` (last 10 inbound) plus `parentMessages` (recent outbound) so the AI has full thread context without a second call. Full schema, error codes, and an **interactive playground** are at [API → Check Replies](/api-reference/endpoint/get-replies). ## Analytics from the MCP The `analytics` tool returns the same metric block the dashboard /analytics page reads, so the AI's answer and the UI agree exactly. Definitions, formulas, and the interactive playground live at [API → Analytics](/api-reference/analytics). ## See Also * [Replies & Inbox](/features/replies) — conceptual model of how replies get matched and surfaced. * [API Reference](/api-reference/introduction) — every endpoint with try-it-now playgrounds. * [API Keys](/api-reference/api-keys) — generating and scoping keys. # Message Templates & Personalization Source: https://docs.tuco.ai/features/message-templates Design, personalize and manage Tuco AI message content safely at scale: templates, variables, fallbacks for missing data and review patterns. ## Overview Tuco AI lets you send highly personalized messages at scale by combining: * **Static templates** you design. * **Dynamic data** from leads and external systems. This page focuses on recommended patterns for: * Template structure and variable usage. * Personalization safety. * Testing and operational practices. It does not depend on any internal APIs—only on behavior visible via the app and documented endpoints. *** ## Template Concepts Think of a Tuco message as: * A **base template**: * Static text and optional placeholders (variables). * **Data bindings**: * Lead fields (first name, company, role, etc.). * Custom fields from your systems. The lead placeholders Tuco resolves for you: * `{firstName}` * `{lastName}` * `{companyName}` * `{email}` * `{phone}` * `{jobTitle}` * `{notes}` — the free-text notes saved on the lead Anything extra your CSV or CRM brought in is stored as a custom field, and goes in by its column name: ``` Hi {firstName}, still running {cf:Franchise Region}? ``` > [!TIP] > > **You do not have to type these from memory.** In the message editor, click **Insert > variable** to see every custom field in your workspace — both the ones synced from HubSpot > or LeadConnector and the ones your CSV imports created. Picking one inserts the exact token, > which matters when a column name has odd spacing or capitalisation. Custom-field names are matched **case-insensitively** and surrounding whitespace is ignored, so `{cf:Industry}`, `{cf:industry}` and `{CF:Industry}` all resolve against a column named `Industry`. Give every one a fallback anyway: ``` Hi {firstName}, still running {cf:Franchise Region|your territory}? ``` > [!WARNING] > > A placeholder Tuco does not recognise is replaced with nothing, not left in the message. If > you invent `{role}`, the send goes out with a gap where you expected a word. Preview a > template before you launch it. *** ## Variable Replacement Behavior (Conceptual) When a message is generated for a particular lead: 1. Tuco reads the template text. 2. For each placeholder: * Looks up the corresponding value on the lead or context object. 3. If a value is: * **Present**: it replaces the placeholder. * **Missing**: it may produce an empty string or a fallback value, depending on your pattern. To avoid awkward messages: * Always design templates with **optional content** in mind. * Use patterns that still read well if some fields are missing. *** ## Safe Template Patterns ### 1. Optional Fields with Natural Defaults Instead of: > "Hi `{firstName}` `{lastName}`, I saw you work at `{companyName}` in `{cf:Franchise Region}`." Prefer: > "Hi `{firstName}`, I saw you work at `{companyName}`." Where: * `{firstName}` is likely to be present (or you fall back to a neutral greeting). * `{companyName}` is often available and safe to include. * `{cf:Franchise Region}` may be omitted entirely to avoid: * "in " with nothing after it. ### 2. Guarding Optional Sections Upstream If your application generates templates programmatically: * Only inject optional phrases if the underlying data exists. For example (pseudo-code in your own system): ```pseudo theme={null} text = "Hi {firstName}" if companyName exists: text += ", I saw you work at {companyName}" text += "." ``` This ensures that if `companyName` is missing, the resulting message still reads naturally. *** ## Personalization Sources ### Lead Fields Base personalization can use: * Lead’s: * First name / last name. * Company name. * Email and phone. * Job title. * Notes — free text your team keeps on the lead. * Custom fields you define. These fields are available in Tuco once you: * Import leads via CSV/CRM. * Create them via the Leads API. ### External Systems If you integrate Tuco with external systems (e.g. CRM, CDP): * Your backend can: * Fetch additional context per lead. * Build final message bodies incorporating that data before calling Tuco. In this model: * Tuco receives the **fully rendered message**. * Tuco still handles delivery, limits, and tracking. *** ## Template Testing Best Practices ### Static Testing Before using a template in production: * Test it with: * Complete data. * Missing optional fields. * Edge cases (short names, unusual characters). Have reviewers read: * Actual example messages generated from real or realistic test contacts. ### In-App Previews If the Tuco UI or your custom UI supports it: * Use preview features to see: * How a template renders for a specific lead. * How segments of leads might see different variations. ### Staging Templates Use non-production workspaces: * Run small test sends against test contacts. * Confirm: * Messages look correct on actual devices. * Personalization behaves as expected. *** ## Compliance & Content Quality While message content is up to you, for best results: * **Clarity and brevity**: * Keep messages focused and concise. * Avoid overloading templates with too many dynamic inserts. * **Tone**: * Ensure tone aligns with your brand and use case. * Avoid language that could be misinterpreted when partial data is missing. * **Consent**: * Only message recipients who have given appropriate consent. * For more on consent and opt-outs, see `/features/compliance-and-optouts`. *** ## Operational Considerations ### Versioning Templates In your own systems: * Keep track of: * Template versions. * Which sends or workflows used which versions. This helps when: * Comparing performance across iterations. * Investigating issues tied to specific content changes. ### Rollbacks Have a plan for: * Rolling back to a previous template version quickly if: * A personalization bug is discovered. * A compliance issue is identified. Use: * Feature flags or config toggles to switch templates without redeploying code. *** ## Summary By treating message templates as: * Carefully designed base texts, and * Composed with safe personalization patterns, you can: * Deliver highly relevant outreach at scale. * Avoid awkward, malformed messages. * Maintain enterprise-grade standards for testing, governance, and compliance—all while leveraging Tuco AI’s delivery, limits, and tracking capabilities. # Rate Limits & Sending Caps Source: https://docs.tuco.ai/features/rate-limits Per-line daily caps, per-minute and per-hour pacing, burst spacing, and what happens to messages that wait (daily cap, line offline, send window). ## Why we cap your sending iMessage delivery is reputation-driven. When an Apple ID suddenly sends a lot of messages in a short window — especially to people who don't know the sender — Apple's spam scoring picks up the pattern and can restrict the Apple ID. Once restricted, iMessage delivery degrades or stops entirely, and there's no way on Apple's side to clear it. So every Tuco line has **daily caps**, **speed limits**, and **burst spacing**. They apply on **every send path** — Quick Send, the dashboard, the API, campaigns, and the HubSpot and GoHighLevel integrations — and they apply again to every message that was held and released later, so a backlog never goes out as a burst. > [!NOTE] > > Everything on this page is **per line**, not per workspace. If you have several lines, each one has its own caps and its own pacing. *** ## New contacts vs. existing conversations Tuco treats two kinds of message differently: * **New contact (first touch):** this line has never sent anything to the recipient before (matched by phone number, email address, or `leadId`). * **Existing conversation:** this line has sent to the recipient before — including a previous message that fell back to SMS, or one that's still waiting to send. Only `cancelled` and `failed` messages don't count. New contacts get the stricter limits, because first messages are what Apple watches most closely. *** ## Daily caps > [card] New contacts per day > > **50 per line per day. This is the maximum and can't be raised.** > > Counts first touches only. Messages in existing conversations don't count toward it. > [card] Total messages per day > > **Default: 150 per line per day.** You can raise it yourself in **Lines → Edit → Daily limits**, but raising it **voids your free first replacement**, and more volume on one number raises the risk of Apple flagging it. > > Counts every outbound message: first touches, follow-ups, and replies. Both reset at **midnight in your workspace's time zone**. See [Raising the caps](#raising-the-caps). *** ## Gaps at a glance ![Default gaps on one line: between new contacts, between follow-ups to different people, and between one person's own messages](https://mintcdn.com/tucoai/SoLkNcvAIeibvkGp/images/rate-limits-gaps.png?fit=max\&auto=format\&n=SoLkNcvAIeibvkGp\&q=85\&s=991909aec5fd8f47c784928c5f533037) | Between… | Normal | After a burst, or after a hold | Limits | | - | - | - | - | | Any two messages on a line | at least 1 second | – | 150 a day | | Two **new contacts** | no extra gap | **2–4 minutes** | 5 a minute · up to 49 an hour · 50 a day | | Follow-ups to **different people** | no extra gap | **5–15 seconds** | 10 a minute · 40 an hour | | **One person's** own messages | always in order, at the gap you planned | at least **1 minute** after a late message (bubbles planned under a minute apart still go together) | – | The sections below explain each number. *** ## Speed limits On top of the daily caps, every line is paced. Limits are rolling windows — "per hour" means any 60-minute period, not the clock hour. | | Per minute | Per 10 minutes | Per hour | | - | - | - | - | | **New contacts** | 5 | 10 | 15 | | **Existing conversations** | 10 | 30 | 40 | * **Hourly new-contact cap.** A line can also have its own hourly cap for new contacts. It's never higher than 15. If it isn't set below the daily new-contact cap, Tuco uses the daily cap ÷ 8 — **7 per hour on a 50-per-day line**. * **Attachments count per part.** A text with an image is 2 sends against these limits, because Apple receives 2 items. A single message is never split across a limit — its parts go out together. *** ## Burst spacing The speed limits stop volume; burst spacing stops a pile of messages leaving in the same few seconds. * **New contacts:** once 3 first touches go out within 30 seconds, the next ones are spaced **2–4 minutes apart** until the line has been quiet for 5 minutes. * **Existing conversations:** once 5 different contacts get a message within 30 seconds, the next ones are spaced **5–15 seconds apart** until the line has been quiet for 2 minutes. * **Held messages** (see below) are spaced like this **from the very first one** when they're released. * Parts of the same message to the same contact (for example a text and its image) always go together. * **Steps of a sequence keep a gap.** If a message to a contact went out late, the next one planned at least 1 minute after it waits at least 1 minute after the late one actually sent — so a backlog never lands three steps on someone in a few seconds. Use `respectGap: true` to keep the full planned gap. See [Keep the wait between follow-ups](/api-reference/endpoint/send-message#keep-the-wait-between-follow-ups). *** ## When messages have to wait Tuco never drops a message because of a limit. It holds it and sends it later — and when held messages are released, they go through the same speed limits and burst spacing, so a backlog drains gradually instead of all at once. | Why it's waiting | When it goes out | | - | - | | **Daily cap reached** | The next morning, from **9:00 AM in your workspace's time zone** (or when your send window opens, if later). Held messages are spread across the following hour, then paced. | | **Hourly new-contact cap reached** | In the next hour. | | **Speed limit or burst spacing** | Seconds to minutes later. | | **Outside your send window, or on a day it isn't allowed to send** | When the window opens on the next allowed day, paced. | | **An earlier message to the same contact is still waiting** | After it, in order. If the two were planned at least a minute apart, at least 1 minute after it. | | **Line offline** | Tuco retries every 5 minutes. When the line is back, the queue is released gradually. After **24 hours** offline, the message is marked failed — see [Failures, Fallbacks & Delivery Outcomes](/features/failures-and-fallbacks). | | **150 messages in a row with no reply** | The line pauses sending and checks again every hour. It resumes as soon as any contact replies on iMessage. A line that nobody answers is exactly what Apple restricts. | ### Daily cap: reschedule or send over your fallback By default, a message that hits a daily cap is rescheduled to the next morning. If you've connected Twilio as your SMS fallback, you can turn on **Settings → Use fallback when a daily limit is reached**. New-contact messages over the cap are then sent over your fallback channel right away instead of waiting. Messages in existing conversations always wait for their own line, so the conversation stays in one thread. When a line hits a daily cap, Tuco emails your workspace once a day with how many messages were rescheduled, unless you've turned that notification off in your email preferences. *** ## What the limits can't protect you from The limits control **how fast and how much** a line sends. They don't control **who** it sends to — and that matters more. A line can stay inside every limit on this page and still get restricted if it texts people who don't expect it: an old list, contacts who never replied, or the same template to a large group of non-repliers. Recipients ignore it or tap **Report Junk**, and Apple restricts the line. A busy line texting people who reply stays healthy; a quieter line texting a cold list doesn't. Before you re-engage old contacts from a CRM workflow, read [What your leads see](/what-leads-see) and the [anti-spam guidelines](/features/anti-spam-guidelines). For reactivation of contacts who haven't replied, use SMS rather than iMessage. *** ## Raising the caps The defaults are sized for typical outbound — small enough that a single line stays well within Apple's tolerance, large enough that day-to-day work isn't constrained. * **New contacts: 50 per line per day is a hard cap.** It can't be raised — not by support, not on any plan. To reach more new contacts, add a line. * **Total messages: 150 per line per day by default.** You can raise it yourself in **Lines → Edit → Daily limits**, but doing so **voids your free first replacement** if the line is banned. * **Follow-ups:** send no more than **4 follow-ups** to someone who hasn't replied. > [!WARNING] > > Raising the total doesn't make your line immune to Apple's spam scoring. About **5** "Report Junk" taps can permanently ban a line, and Apple doesn't notify anyone when you're reported — so there's no count to watch. *** ## Recommended pacing if your line was recently flagged If we've reset your line after an Apple flag (or you're starting on a fresh Apple ID), use a conservative warm-up: | Week | Daily new-contact cap | | - | - | | Week 1 | 10 | | Week 2 | 20 | | Week 3 | 30 | | Week 4+ | Back to your normal cap | Spread sends across business hours; don't fire your full daily budget in one 30-minute window. *** ## How to tell if you're approaching a cap In the app: 1. Go to **Lines** in the left nav. 2. Click into a line. The "Today's usage" panel shows your current new-contact count and total-message count vs. the cap. *** ## Related * [Failures, Fallbacks & Delivery Outcomes](/features/failures-and-fallbacks) — what happens to messages that don't deliver * [Spam Monitor](/features/spam-monitor) — how we detect when Apple flags your line * [Line health & restrictions](/troubleshooting/line-health-and-restrictions) — what gets a line restricted * [Health Checks](/architecture/health-checks) — per-line availability monitoring # iMessage Reactions Source: https://docs.tuco.ai/features/reactions Send and receive iMessage reactions (tapbacks) through Tuco. Incoming reactions are stored, not treated as replies, and can fire a webhook. ## Supported Reactions | Reaction | Emoji | Description | | - | - | - | | Love | ❤️ | Heart reaction | | Like | 👍 | Thumbs up | | Dislike | 👎 | Thumbs down | | Laugh | 😂 | Ha ha | | Emphasize | ‼️ | Exclamation | | Question | ❓ | Question mark | | Custom | Any emoji | iOS 18+ custom emoji tapbacks | ## Inbound Reactions When a lead reacts to a message: * The reaction is detected and stored (not shown as a text message) * No AI call is triggered — reactions are not treated as replies * No notification is sent to the contact owner * Tuco can also emit a `message.reaction` webhook for integrations that want to track reactions in real time ## Outbound Reactions React to lead messages from the Unibox — hover over a message to see the reaction picker. You can also send reactions through the API using `POST /api/messages/react`. See the [Send Reaction API reference](/api-reference/endpoint/send-reaction). If you want to sync inbound reactions into your CRM or automation layer, see [Message Webhooks](/api-reference/message-webhooks). ## How Reactions Appear Reactions are displayed as emoji overlays on the original message bubble in Unibox, matching the native iMessage experience. # Lead Reactivation Source: https://docs.tuco.ai/features/reactivation Find leads that went cold in Tuco (no reply in X days, last contacted long ago, from a list or source) and re-engage them with a new message. ## What Reactivation Does Reactivation identifies leads who haven't engaged recently and lets you re-engage them. Find leads that went cold and bring them back. ## How It Works 1. Go to **Leads → Re-activation** tab 2. Set your criteria: * No reply in X days * Last contacted more than X days ago * From specific lists or sources (HubSpot, GHL, CSV) 3. Preview matching leads 4. Export the list, then send your re-engagement messages from a [GoHighLevel](/integrations/ghl) (or your CRM) workflow ## Re-activation Sources | Source | Description | | - | - | | All leads | Any lead in your workspace | | HubSpot Import | Leads synced from HubSpot | | GHL Import | Leads synced from GoHighLevel | | CSV imports | Leads uploaded via CSV | | API leads | Leads created via the API | ## Best Practices * **Wait at least 14 days** before re-activating — give leads time to respond * **Use a different message** — don't repeat your original outreach * **Check DNC status** — leads who opted out should not be re-activated * **Track results** — compare re-activation reply rates vs initial outreach # Registered Caller ID Setup Source: https://docs.tuco.ai/features/registered-caller-id The business details carriers need before your calls can show your company name: where to enter them, the rules, and what happens after you submit. **Registered caller ID shows your business name when you call. Before carriers allow that, they need to know your business. You tell us once, in a short form that takes about 3 minutes.** Registered caller ID is a calling add-on: $50 setup + $50/mo per line + \$0.075 per call. To learn what it does and how to buy it, see [Calling & Add-ons](/features/calling-add-ons). > [!NOTE] > > You fill in the form **once for your whole workspace**. Every line with Registered caller ID uses the same details. ## Where to find the form The form is called **"Caller ID details: needed to turn on Registered caller ID"**. You'll see it in three places: * **The line order page right after checkout**, if you picked Registered caller ID at checkout. * **Lines → Provision Line**, in the **Calling** step, when you tick Registered caller ID or already paid for it at checkout. * **Lines → Calling**, on any line that has Registered caller ID, including after it's live. **Your line is ordered either way.** You don't have to finish the form to order a line. You can fill it in later from **Lines → Calling**. ## What the form asks for Some details may already be filled in from your line order. Check them before you submit. ### What people see when you call * **Name shown on calls.** Your company or brand, **not a person's name**. Up to **35 characters**. No emoji. * **Reason for calling.** Pick one from the list, such as *Sales Call*, *Follow-Up Calls* or *Appointment Reminder*. It shows under your name on some phones. You can add up to two more reasons (optional). * **Logo (optional).** Shows on supported phones. Use a square image. ### Your business * **Company legal name** * **Name customers know you by (DBA)** * **Website** * **Federal tax ID (EIN).** 9 digits, like 12-3456789. * **Type of company.** Corporation, LLC, Partnership, Nonprofit or Other. * **State where it's registered** * **Industry.** Pick the closest one, such as *Finance, lending or debt relief*. * **Number of employees.** Pick a range. ### Business address Street address, suite (optional), city, state and ZIP. If your billing address is different, untick **Billing address is the same** and enter it. ### Main contact First name, last name, job title, email and phone. The phone must be a US or Canada number. Type it any way you like, such as (305) 555-0100. **This person signs one short letter that lets us register your caller ID numbers.** Pick someone who can sign for the business, such as the owner. If someone else handles billing, untick **Same person handles billing** and add their name, email and phone. ### Area code (optional) Calls with Registered caller ID come from a separate number we register for you. Enter the area code you'd like for it, or leave it empty to match each line. ### The confirmation Tick the box to confirm that the name and logo accurately represent your business, that you own or are allowed to use them, and that your calls contain no sex, hate, alcohol, firearms or tobacco content. ## Save for later, or Submit At the bottom of the form there are two buttons. * **Save for later** keeps what you've typed, even if the form isn't finished. You'll see *"Saved. You can finish this any time from Lines → Calling."* Nothing is sent for registration yet. * **Submit caller ID details** sends your details to us. Every field must be filled in, except the ones marked optional. If something is missing, the form tells you exactly what, for example: *"Please fill in: Website, Federal tax ID (EIN)."* Even **Save for later** won't keep a value that is clearly wrong. For example, a name longer than 35 characters or with emoji, an EIN that isn't 9 digits, an area code that isn't 3 digits, or an email or website that doesn't look right. The form tells you which one to check. When you submit, you'll see *"Thanks! We have everything we need to register your caller ID."* The box turns green and shows the name you chose. ## Changing your details after you submit Click **Edit** on the green box, change what you need, and click **Save changes**. We update it with the carriers. Click **Cancel** to keep your details as they were. You can do this any time, including after your caller ID is live. Your details stay on **Lines → Calling**. ## What happens next * **We register your business with the carriers.** This usually takes a few business days. * **Your main contact signs one short letter** that lets us register your caller ID numbers. * **We email you when it's live.** On **Lines → Calling**, the add-on then shows **Active** and the number your calls go out from. Once it's live, your business name shows on **US-to-US calls to mobiles on T-Mobile and Verizon**. Your texts still come from your line's own number. Each Registered caller ID call costs \$0.075, added to your next invoice. ## Frequently asked questions > [accordion] Do I have to fill this in before my line is ordered? > > No. Your line is ordered either way. Registered caller ID just can't go live until you submit your details. > [accordion] Can I use my own name as the name shown on calls? > > No. It has to be your company or brand, not a person's name. > [accordion] Why do you need my EIN and address? > > Carriers need to know your business before your calls can show your name. > [accordion] I have several lines. Do I fill this in for each one? > > No. One form covers your whole workspace. Every line with Registered caller ID uses it. > [accordion] Does this change the number my texts come from? > > No. Calls with Registered caller ID come from a separate registered number. Your texts still go out from your line's own number. ## For developers You can read and send these details with the [Caller ID Details API](/api-reference/endpoint/caller-id-profile). # Replies & Inbox Source: https://docs.tuco.ai/features/replies Tuco captures replies, links them to the right lead and conversation, and makes them available in the app, your CRM and your own workflows. ## What Reply Handling Gives You Tuco doesn’t just send messages—it also **captures replies**, links them back to the right lead and conversation, and makes them available to you: * In the Tuco UI (inboxes and timelines). * Through APIs and exports. * Via webhooks you can plug into your own systems. From your point of view, replies become a first‑class signal you can use to: * Route conversations to humans. * Update CRM timelines. * Trigger follow‑ups or automations. You never need to manage how replies are matched internally; Tuco handles that. *** ## How Replies Show Up in Tuco When a recipient replies on a supported channel: * The reply is attached to: * The relevant **lead**, where known. * The originating message, where a match is clear. * The reply content and timestamp are visible: * In the Tuco app (conversation view, lead history). * Through public APIs and exports. Typical things your team can see: * Last reply content and time for each lead. * Which line and channel the reply came back on. *** ## Using Replies in Your Workflows Replies are especially powerful when you connect them to your own tools. ### In your CRM By consuming reply events (see `/api-reference/message-webhooks`), you can: * Add timeline entries with: * Reply text. * When it was received. * Which message it refers to. * Update fields like: * “Last replied at”. * “Reply sentiment” (if you classify it). This gives sales and support teams a complete picture of conversations without leaving the CRM. ### In your automations Replies can be treated as triggers for: * Moving a lead to the next stage in your funnel. * Creating tasks for an owner to respond. * Stopping later follow-ups for that lead in your [GoHighLevel](/integrations/ghl) (or CRM) workflow. * Performing routing (for example, assigning conversations by region or product line). You decide the rules in your own systems; Tuco provides reliable events with stable identifiers. *** ## Reply Webhooks (Conceptual Overview) When you enable reply webhooks, Tuco sends a notification to your backend whenever a new reply is recorded. At a high level, each event includes: * **Which message** was replied to (when known). * **Which lead** it relates to (when known). * **Which workspace and line** own the conversation. * **The body of the reply**. * **Timestamps** so you can order events in your own logs. * **`repliedAtUtc`** — when the reply was received (UTC). Always present. * **`parentMessages`** — the last 2 outbound messages you sent to that lead in the workspace. Omitted when none exist. All of this is backward compatible: existing fields are unchanged; new fields are additive. For concrete field names and shapes, see `/api-reference/message-webhooks`. Those schemas are the stable contracts you should integrate against; you do not need to know anything about the internal bridging or storage layers. *** ## Behavior When No Perfect Match Exists In real life, you may see replies that: * Come from a contact you messaged long ago. * Come from a slightly different address or number than the one you used. * Don’t clearly match a recent outbound message. From your perspective: * Tuco will still try to associate the reply with: * The closest known lead. * The most relevant recent conversation. * When a clean match isn’t possible, Tuco: * Avoids guessing in ways that would corrupt your data. * Still preserves the raw reply information where it can be safely attached. Because of this, you can trust that: * When a reply is shown as belonging to a lead, Tuco has already done the heavy lifting to match it. * You’re not exposed to the internal matching heuristics—only to outcomes that are safe to build on. *** ## Patterns for Classifying Replies Many teams treat replies as more than just free‑form text. Common patterns include: * **Interest level** * “Interested”, “Not now”, “Not interested”. * **Intent** * “Book a meeting”, “Ask a question”, “Negotiate pricing”. * **Compliance** * “Opt‑out” or “Unsubscribe” messages (see `/features/compliance-and-optouts`). You can implement classification: * In your own backend by: * Examining reply text from webhooks. * Applying your own NLP models or rule‑based logic. * In your CRM using: * Formulas or automation workflows acting on the reply content and tags. Tuco’s responsibility is to deliver the raw reply in a consistent format and context; your responsibility is to decide how to interpret and act on it. *** ## Operational & Analytics Use Cases Once replies are flowing reliably, you can: * **Measure engagement** * Reply rates per line, per segment, or per rep. * Breakdown of classifications (e.g. positive vs negative replies). * **Improve targeting** * Identify segments that consistently reply positively. * Suppress or adjust outreach for segments with high complaint or opt‑out replies. * **Refine content** * Compare reply patterns across different templates. * Use replies to inform future copy and cadences. All of these insights come from the data Tuco already exposes; you never need to access any internal worker endpoints or logs. *** ## Best Practices * **Normalize identifiers upstream** * Store phone numbers in a consistent format (e.g. E.164). * Lowercase emails before storing. * This makes reply‑to‑lead matching more accurate. * **Keep one source of truth for routing** * Decide in your own systems how replies: * Are assigned to owners. * Affect deal or account stages. * **Respect consent and expectations** * Use reply content to: * Honor opt‑outs quickly. * Avoid over‑messaging after clear “not interested” replies. * **Log and monitor** * Capture reply events in your logging and analytics tools. * Watch for sudden changes in reply volume or tone that may indicate an issue with a line or template. Handled this way, Tuco’s reply features give you a reliable **feedback loop** for your outreach, while keeping all underlying implementation detail safely abstracted away. # Retroactive Conversation Scanner Source: https://docs.tuco.ai/features/retroactive-scanner Scan past Tuco conversations for leads that went cold, where the last message is older than a set number of days, and trigger follow-ups. Scan past conversations to identify leads that have gone cold and trigger follow-up actions. ## API ### Scan for Dormant Conversations ```bash theme={null} GET /api/conversations/scan-dormant?days=7&limit=50 ``` Returns conversations where the last message is older than `days` days. **Response:** ```json theme={null} { "dormantConversations": [ { "recipientPhone": "+19045551234", "lastMessageAt": "2026-04-10T15:30:00Z", "lastMessageDirection": "received", "leadName": "John Smith", "daysSinceLastMessage": 7, "messageCount": 12 } ], "total": 23 } ``` ### Take Action ```bash theme={null} POST /api/conversations/scan-dormant { "action": "notify", "conversationIds": ["+19045551234", "+18135551234"] } ``` **Actions:** * `notify` — Sends a Telegram summary of dormant leads * `draft` — AI drafts personalized follow-ups for each conversation using KB + conversation history ## How Drafts Work When you trigger `draft`, the scanner: 1. Fetches the last 10 messages for each conversation 2. Enqueues a KB auto-reply job with `[DORMANT FOLLOW-UP]` context 3. The KB worker generates a context-aware follow-up 4. In copilot mode: draft appears in Telegram for approval 5. In autopilot mode: sends automatically if confidence is high enough # Send Messages Source: https://docs.tuco.ai/features/send-messages Send iMessage, SMS or email to leads or one-off recipients with Tuco, immediately or scheduled, for single-lead and bulk outreach. ## Overview Send iMessage, SMS, or email to leads or arbitrary recipients. Messages can be sent immediately or scheduled for later delivery. > [card] [Quick Send](#quick-send) > > Send one-off messages without creating leads > [card] [Send to Leads](#send-to-leads) > > Single-lead and bulk outreach *** ## Quick Send Perfect for testing, one-off messages, or contacting people not in your system. > [!NOTE] > > **No lead required** - Send directly to any phone or email address ### How to Quick Send **1. Open Quick Send** Navigate to **Leads → Import** and click **Quick Send** button **2. Enter Recipient** Type recipient address: * **Phone:** Include country code (e.g., +12025551234) * **Email:** Full email address **3. Check Availability** System **automatically checks** iMessage availability: * 🔵 Blue icon - iMessage available * ⚪ Gray icon - Will send as SMS/email **4. Compose Message** Type your message in the text area **5. Choose Timing** Select delivery time: * **Send Now** - Immediate delivery * **Send Later** - Schedule for specific date/time **6. Send** Click **Send Now** or **Schedule Message** ### Limitations > [!WARNING] > > * Cannot send to unavailable addresses (button will be disabled) > * Must have an active line configured > * Message length limits apply based on type *** ## Send to Leads The recommended method for follow-ups and organized outreach. ### Single Lead Message Send to one lead at a time: 1. Navigate to **Leads** page 2. Find and select a lead (checkbox) 3. Click **Send Message** in toolbar 4. Compose and configure message 5. Click **Send** ### Bulk Messaging Send to multiple leads simultaneously: **1. Select Leads** Check multiple leads in the table **2. Open Message Composer** Click **Send Message** (bulk action) **3. Compose Message** Type your message (same for all recipients) **4. Choose Message Type** System automatically selects optimal type: * **iMessage** - If available * **SMS** - Fallback for unavailable iMessage * **Email** - Email delivery **5. Set Timing** Choose immediate or scheduled delivery **6. Send Batch** Click **Send** - progress indicator shows completion > [!NOTE] > > **Batch Processing:** Messages are sent sequentially with individual delivery status per lead. *** ## Message Types Choose the right message type for your communication: > [card] iMessage > > **Blue bubble** > > Apple iMessage delivery > > Requires: iMessage enabled > [card] SMS > > **Green bubble** > > Standard text message > > Requires: Any mobile number > [card] Email > > **Email delivery** > > Email client delivery > > Requires: Valid email address > [!TIP] > > The system **automatically selects** the best delivery method based on availability checks. *** ## Scheduling Messages Send messages at the perfect time, even when you're not available. ### Schedule for Later **1. Select 'Send Later'** Choose the scheduling option when composing **2. Pick Date** Use calendar picker to select date **3. Pick Time** Use time picker for specific hour/minute **4. Validation** System validates: * Must be future date/time * Cannot be in the past **5. Queue Message** Message saved with **Scheduled** status ### How Scheduled Messages Work ```mermaid theme={null} graph LR A[Schedule Message] --> B[Queue with Timestamp] B --> C[Cron Job Runs] C --> D{Time Reached?} D -->|No| C D -->|Yes| E[Send Message] E --> F[Update Status to Sent] ``` > [!NOTE] > > **Processing:** Scheduled messages are processed by a cron job that runs every minute. ### Managing Scheduled Messages View and manage your scheduled messages: 1. Navigate to **Messages** page 2. Filter by status: **Scheduled** 3. Can cancel messages before send time 4. Edit or reschedule as needed *** ## Message Tracking Every message includes comprehensive tracking data: ### Message Properties **status** `string` Current message state: * `Sent` - Successfully delivered * `Scheduled` - Queued for future send * `Failed` - Delivery failed * `Cancelled` - Manually cancelled **timestamp** `string` When message was sent or scheduled **recipient** `object` Lead reference or direct address **fromLine** `string` Which line sent the message **messageType** `string` iMessage, SMS, or Email **batchId** `string` For bulk sends - links related messages ### View Message History Access complete message logs: 1. Navigate to **Messages** page 2. Use filters: * Status * Date range * Message type * Recipient 3. Search by content or recipient name 4. Export for analysis *** ## API Reference Send messages programmatically via REST API. ### Send Message Endpoint ```bash theme={null} POST /api/messages ``` **Headers:** ```json theme={null} { "Content-Type": "application/json", "Authorization": "Bearer " } ``` **Request Body:** ```json theme={null} { "message": "Hello! This is a test message.", "messageType": "imessage", "fromLineId": "507f1f77bcf86cd799439011", "recipientPhone": "+12025551234", "recipientName": "John Doe", "scheduledDate": "2025-10-15T14:30:00Z", "leadId": "507f1f77bcf86cd799439012" } ``` ### Request Parameters **message** `string` *required* Message text content **messageType** `string` *required* One of: `imessage`, `sms`, or `email` **fromLineId** `string` *required* ID of the line to send from **recipientPhone** `string` Phone number (required if no recipientEmail) **recipientEmail** `string` Email address (required if no recipientPhone) **recipientName** `string` Display name for recipient **scheduledDate** `string` ISO 8601 timestamp for scheduled delivery **leadId** `string` Associated lead ID (optional) **batchId** `string` Batch identifier for bulk operations **Response:** ```json theme={null} { "success": true, "message": { "_id": "507f1f77bcf86cd799439013", "message": "Hello! This is a test message.", "messageType": "imessage", "status": "sent", "createdAt": "2025-10-14T10:30:00Z" } } ``` ### Error Codes | Code | Description | | - | - | | `400` | Missing required fields or invalid data | | `401` | Unauthorized - invalid or missing token | | `404` | Lead or line not found | | `500` | Server error - delivery failed | > [card] [Complete API Docs](/api-reference/messages) > > View detailed API documentation with more examples *** ## Best Practices ### ✅ Do's > [accordion] Check Availability First > > Always verify iMessage availability before bulk sending to maximize delivery rates > [accordion] Use Scheduling Wisely > > Schedule messages for optimal times based on your audience's timezone and habits > [accordion] Personalize Messages > > Use lead data to personalize messages and increase engagement > [accordion] Test First > > Use Quick Send to test messages before sending to your full list > [accordion] Monitor Delivery > > Regularly check delivery status and adjust strategy based on results ### ❌ Don'ts > [!WARNING] > > **Avoid these common mistakes:** > > * ❌ Sending to unchecked addresses > * ❌ Spamming recipients with multiple messages > * ❌ Sending without an active line configured > * ❌ Using all caps or excessive punctuation > * ❌ Sending promotional content without consent > * ❌ Ignoring delivery failures and errors *** ## Troubleshooting > [accordion] Message Failed to Send > > **Common causes:** > > * Recipient address is invalid > * Line is not active or misconfigured > * Server connection issue > > **Solution:** Verify recipient address, check line status, and retry > [accordion] Scheduled Message Didn't Send > > **Common causes:** > > * Line became inactive > * Server was down at scheduled time > * Message was cancelled > > **Solution:** Check message status in Messages page, verify line is active > [accordion] Cannot Send to Unavailable Address > > **Cause:** Recipient doesn't support iMessage and message type is set to iMessage only > > **Solution:** Change message type to SMS or Email, or use auto-select mode # Spam Monitoring Source: https://docs.tuco.ai/features/spam-monitor Track Tuco AI line health, failure rates, and spam risk in real time. Works with HubSpot, Salesforce, GoHighLevel, and direct iMessage flows. Monitor your lines for spam risk based on delivery failure rates and consecutive failures. ## API ```bash theme={null} GET /api/lines/spam-monitor ``` **Response:** ```json theme={null} { "lines": [ { "lineId": "abc123", "linePhone": "+19045551234", "lineType": "phone", "totalSentLast24h": 150, "failedLast24h": 3, "failureRate": 2.0, "consecutiveFailures": 0, "spamRisk": "low", "recommendation": "Line is healthy." } ] } ``` ## Risk Levels | Risk | Failure Rate | Action | | - | - | - | | **Low** | \< 5% | No action needed | | **Medium** | 5-15% | Reduce send volume by 50%, monitor 24h | | **High** | > 15% | Pause sending immediately, wait 24-48h | ## Automated Alerts The health check cron calculates failure rates and records events internally: High- and medium-risk lines are flagged automatically; check the **Lines** dashboard for the current risk level. Line-down email alerts are sent automatically after 7 consecutive failures. # Telegram Integration Source: https://docs.tuco.ai/features/telegram Connect Telegram to your Tuco workspace for real-time reply notifications and answer leads directly from Telegram. Link it with the bot's /start link. ## What Telegram Does Connect Telegram to your Tuco workspace for: * **Real-time reply notifications** with lead name and message preview * **Reply directly from Telegram** — your response is sent as an iMessage to the lead * **KB copilot drafts** with Approve/Reject buttons * **Billing events** ## Connecting Telegram 1. Go to **Integrations → Telegram** 2. Click the deep link to open the Tuco bot in Telegram 3. Send `/start` — your workspace is linked ### Per-Member Linking Each team member can link their own Telegram account. Reply notifications are routed to the **contact owner's** personal Telegram, not just the workspace channel. ## Bot Commands | Command | Description | | - | - | | `/whoami` | Shows workspace name, plan, line count, member count | | `/send +1234567890 message` | Send an iMessage directly from Telegram | | Reply to notification | Your reply is sent as an iMessage to the lead | ## Knowledge Base Integration When KB mode is set to **Copilot**: 1. Lead replies → KB generates a draft 2. Draft is sent to your Telegram with **Approve** / **Reject** buttons 3. Tap Approve → reply is sent to the lead 4. Tap Reject → discard the draft, reply manually ## Notification Routing | Scenario | Where notification goes | | - | - | | Contact owner has Telegram linked | Owner's personal Telegram | | No personal link | Workspace Telegram channel | | No workspace Telegram | Email only | | Global support | Always copied to support channel | # Upload Leads Source: https://docs.tuco.ai/features/upload-leads Import leads into your Tuco workspace by CSV upload, Google Sheets, HubSpot or Salesforce. New to importing? Start with the CSV upload. ## Overview Import leads into your workspace using multiple methods: CSV upload, Google Sheets, HubSpot, or Salesforce integration. > [card] Quick Start > > New to importing leads? Start with **CSV Upload** for the easiest experience. *** ## CSV Upload The recommended method for beginners. Upload a CSV file with your lead data. ### Step 1: Prepare Your CSV File Your CSV must include these **required fields**: **firstName** `string` *required* Lead's first name **lastName** `string` *required* Lead's last name **email** `string` *required* Primary email address **phone** `string` *required* Primary phone number (include country code, e.g., +1234567890) **Optional fields:** **altPhone1** `string` Alternate phone numbers **altPhone2** `string` Alternate phone numbers **altPhone3** `string` Alternate phone numbers **altEmail1** `string` Alternate email addresses **altEmail2** `string` Alternate email addresses **altEmail3** `string` Alternate email addresses **companyName** `string` Company or organization name **jobTitle** `string` Position or role **linkedinUrl** `string` LinkedIn profile URL **notes** `string` Free-text context about the lead. Your team can read and edit it later, and your AI goal bots use it when they write — see [Lead notes](#lead-notes). **contactOwnerEmail** `string` Email of the workspace user to assign as owner. Must match a user in your workspace. Invalid or missing values default to the first workspace user. > [!NOTE] > > Any additional columns will be stored as **custom fields**. ### Step 2: Download Template (Optional) Click the **Download Template** button to get a pre-formatted CSV with all fields. ### Step 3: Upload Your File 1. Navigate to **Leads → Import** 2. Select **CSV File** method 3. Drag & drop your file or click **Choose File** 4. File size limit: **10MB max** ### Step 4: Select or Create a List Choose whether to: * Add to an **existing list** (select from dropdown) * Create a **new list** (enter list name) ### Step 5: Map Fields The system will **auto-map** common field names. Review and adjust: * Each CSV column maps to one lead field * Required fields must be mapped * See live preview of sample data #### Custom variables Any column you do **not** map to a standard field is imported as a **custom variable**. The mapping step lists every one of them in a **Custom variables** section, showing: * a toggle to import it or ignore it (everything is ON by default) * the variable name, which you can rename * the exact token it will produce, e.g. `{cf:Industry}` * a sample value from your first row Rename a variable here and the token updates with it — what you see is what your messages will use. > [!TIP] > > This is how you get your own data into messages. A column called `Industry` becomes > `{cf:Industry}`, usable in any message. See > [Message Templates](/features/message-templates) for the full syntax. > [!WARNING] > > Turn OFF the columns you do not need. Tracking columns like `utm_source` or internal row > IDs become variables too, and they clutter the variable picker in the message editor. ### Step 6: Preview & Import * Review first 10 records * See validation summary (valid leads, invalid records) * **Custom variable columns appear in the preview table** with their real values, so you can confirm the data landed on the right variable before importing * Click **Import** to save **Import Results:** * ✅ Number of leads saved * ⚠️ Invalid records skipped * 📋 List assignment confirmation * 🏷️ Custom variables imported, named, with the `{cf:...}` syntax to use them #### Duplicates A lead already in your workspace is **skipped, not re-imported** — matched on any of its phone numbers or email addresses, not just the primary one. > [!WARNING] > > A skipped duplicate **stays in its original list**. Importing an existing contact into a new > list does not move it there, and does not add it to both — a lead belongs to exactly one > list. To move existing leads, use **Add to list** on the Leads page, which reports the > conflicts and lets you transfer them deliberately. *** ## Google Sheets Integration Import leads directly from Google Sheets. ### Prerequisites **1. Google API Access Token** Generate an access token from Google Cloud Console **2. Spreadsheet ID** Found in your Google Sheet URL **3. Sheet Name** Default: "Sheet1" (optional parameter) ### Import Steps 1. Navigate to **Leads → Import** 2. Select **Google Sheets** 3. Enter credentials: * Access Token * Spreadsheet ID * Sheet Name (optional) 4. Click **Connect & Import** > [!NOTE] > > Your Google Sheet must follow the same field structure as CSV (see above). *** ## HubSpot Integration > [!NOTE] > > **Premium Feature** - Requires HubSpot account and premium plan ### Features * ✓ Bidirectional sync * ✓ Contact properties * ✓ Deal tracking * ✓ Activity logs ### Setup Steps 1. Navigate to **Leads → Import** 2. Select **HubSpot** 3. Click **Authorize & Import** 4. Log in to HubSpot and grant permissions 5. System automatically imports contacts *** ## Salesforce Integration > [!NOTE] > > **Premium Feature** - Requires Salesforce account and premium plan ### Features * ✓ Lead & Contact sync * ✓ Custom fields support * ✓ Opportunity data ### Setup Steps 1. Navigate to **Leads → Import** 2. Select **Salesforce** 3. Click **Authorize & Import** 4. Log in to Salesforce and grant permissions 5. System automatically imports leads *** *** ## Lead notes `notes` is one free-text field on the lead — a place for the context that does not fit a column. "Quoted in March, went quiet." "Only answers after 5pm." "Property address: 8 Williams Wood Rd; lead score: high." **Where to edit it** * **Leads → open a lead → Edit** — the Notes box at the bottom of the contact details. The saved note shows as its own **Notes** card on the lead page. * **Unibox → the contact button on a conversation** — opens the same contact panel with the same Notes box, so you can write one down mid-conversation. * **CSV import** — map a column to `notes`, or send `notes` on the Leads API. This sets the note on **new** leads only: re-importing someone you already have is treated as a duplicate and leaves their existing note untouched, so notes cannot be bulk-rewritten by re-uploading a file. To clear a note, empty the box and save. There is no separate delete. **What reads it** * **Goal bots and task agents** — returned by their `get_lead_details` tool. * **`{notes}` in a message template** — inserts the note verbatim, so use a fallback (`{notes|}`) if only some leads have one. > [!WARNING] > > Notes are internal context, not message copy. Bots are told to use a note for context and > never to read it back to the lead, but `{notes}` in a template pastes it into the message > exactly as written — do not put anything there you would not want a lead to see. > > Very long notes are truncated before they reach a model, so keep them to the facts that > matter. *** ## Managing leads in bulk Everything below lives on the **Leads** page and respects whatever filter you currently have applied — list, search, or owner. ### Selecting more than one page The Leads page shows 50 rows at a time, so the header checkbox selects those 50. When more leads match your filter than fit on the page, Tuco offers a wider scope: * **All N matching** — every lead in the current list or filter * **All N in HubSpot / LeadConnector** — every lead carrying a record ID for your connected CRM (only shown when a CRM is actually connected) The counts come from the server, so they are the true totals, not what is on screen. The page scope stays the default — nothing is escalated without you choosing it. ### Delete all matching leads **Delete all N** removes every lead in the chosen scope, along with their activities, messages, conversation history and stats. You must type the count to confirm. > [!WARNING] > > This is permanent and cannot be undone. **Delete all N** keeps the list itself — it only removes the leads. **Delete List** is the separate action that removes the list as well. ### Add leads to a list **Add to list** moves the selected scope into a list you pick. Because a lead belongs to exactly one list, any lead already in a *different* list is reported rather than silently moved. Tuco shows a **duplicate report** naming each one and the list it is currently in, and offers: * **Download CSV** — the conflicted leads with their current and target list, so you can decide outside the app * **Transfer to this list** — moves them, which **removes them from their old list** Leads with no list are added immediately. Leads already in the target list are left alone. ### Bulk operations run in the background A bulk delete or transfer across tens of thousands of leads does not run while you wait. Tuco confirms with a toast — *"Deleting 60,000 leads from Q4 Push in the background. This can take a few minutes."* — and works through it. While an operation is in flight, that list is **locked**: further bulk actions on it are disabled and the list shows as *deleting in background* in the filter. Other lists stay fully usable. > [!NOTE] > > The lock is held on the server, not in your browser, so it survives a reload and is visible > from a second tab. Trying to start a conflicting operation returns a clear error rather than > running twice. A bulk action that covers **all** leads (rather than one list) locks every list for its duration, because it can touch leads anywhere. Two different lists can still be worked on at the same time. ### If something goes wrong Bulk operations are not silent about failure. If one stops early — because it could not remove some leads, or because the server restarted mid-run — Tuco tells you what happened and how far it got: > **Bulk operation didn't finish** — Deleting 60,000 leads stopped unexpectedly. 12,000 of > 60,000 were processed. The server restarted while this was running. Re-run to finish the rest. The operation is safe to re-run: it picks up whatever is still matching and leaves the rest alone. You will see this message once, the next time you open the Leads page. *** ## Data Validation Rules ### Phone Numbers Phone numbers are automatically formatted according to these rules: | Input Format | Output Format | Description | | - | - | - | | 10 digits | +1XXXXXXXXXX | Assumes US number | | 11 digits (starts with 1) | +1XXXXXXXXXX | US number with country code | | Other formats | Must be E.164 | International: +\[country]\[number] | ### Email Addresses * Must contain `@` and `.` * Automatically converted to lowercase * Whitespace trimmed ### Duplicate Detection > [!WARNING] > > Duplicates are detected by email address: > > * Duplicate rows in same CSV are skipped > * Existing database duplicates are handled gracefully *** ## API Reference Upload leads programmatically using our REST API. > [card] [API Endpoint](/api-reference/leads) > > View complete API documentation for lead uploads ### Quick Example ```bash theme={null} POST /api/leads ``` **Request:** ```json theme={null} { "leads": [ { "firstName": "John", "lastName": "Doe", "email": "john@example.com", "phone": "+12025551234", "companyName": "Acme Corp", "jobTitle": "CEO", "contactOwnerEmail": "rep@yourcompany.com", "customFields": { "industry": "Technology", "revenue": "1M-5M" } } ], "listId": "507f1f77bcf86cd799439011", "source": "csv_import" } ``` **Response:** ```json theme={null} { "message": "Leads saved successfully", "savedCount": 1, "listId": "507f1f77bcf86cd799439011" } ``` ### Error Codes | Code | Description | | - | - | | `400` | Invalid data or missing required fields | | `401` | Unauthorized (missing/invalid auth token) | | `404` | List not found | | `500` | Server error | *** ## Best Practices > [accordion] ✅ Use Templates > > Download and use our CSV template to ensure proper formatting > [accordion] 📋 Validate Before Upload > > Review your data for completeness and accuracy before importing > [accordion] 🗂️ Organize with Lists > > Create specific lists for different outreach or lead sources > [accordion] 🔄 Regular Syncs > > Set up automated syncs with HubSpot/Salesforce for up-to-date data # Apple Messages for Business vs an iMessage API Source: https://docs.tuco.ai/guides/apple-messages-for-business-vs-imessage-api Two different products. Messages for Business is Apple's inbound support channel on your brand entry points. An iMessage API sends outbound from a real line. **They are different products solving opposite problems. Apple Messages for Business is Apple's official programme that lets customers start a conversation with your brand from Apple entry points, and it is inbound-first — the customer messages you. An iMessage API like Tuco sends outbound iMessage from a real, dedicated Apple line you control, so you can follow up with a contact who already engaged.** If you want a support channel customers discover through Apple, you want Messages for Business. If you want your CRM to send a blue-bubble follow-up, you want an iMessage API. ## Side by side | | Apple Messages for Business | iMessage API (Tuco) | | - | - | - | | Direction | Inbound-first — the customer opens the conversation | Outbound and inbound | | Who starts it | The customer, from Maps, Safari, Search or your buttons | You, to a contact who already engaged with you | | Identity shown | Your brand, with logo and brand name | A real phone number or Apple ID on a dedicated line | | Approval | Apple programme approval, plus a messaging service provider | No Apple programme approval; your line runs on dedicated Apple hardware | | Typical use | Customer support, order status, pre-sales questions | Speed-to-lead follow-up, appointment reminders, re-engagement | | CRM sending | Through your provider's integration | Direct from HubSpot, GoHighLevel, n8n, or the API | ## Why people confuse them Both put your business into the Messages app, so search results treat them as the same thing. The practical difference is who is allowed to send first. Messages for Business is designed so a customer taps a button and lands in a conversation with your brand. It is excellent for support, and Apple gives it brand identity — your name and logo. What it does not give you is the ability to initiate outbound messages to a list. An iMessage API is the other half. Tuco provisions a dedicated line on real Apple hardware, checks whether each contact can receive iMessage, sends from that line, and routes anyone who cannot to your SMS fallback. That is what makes CRM-triggered follow-up possible. > [!NOTE] > > Outbound capability is not permission to cold-message. Tuco is for warm contacts who already engaged — form-fills, ad opt-ins, replied prospects and customers. See [iMessage compliance and TCPA](/guides/imessage-compliance-tcpa) and the [anti-spam guidelines](/features/anti-spam-guidelines). ## Which one you actually need **1. Customers should be able to find and message you** That is Apple Messages for Business. Apple approval plus a messaging service provider. **2. Your CRM should send a blue-bubble follow-up after a lead engages** That is an iMessage API. Start with [Send iMessage from HubSpot](/guides/send-imessage-from-hubspot) or [from GoHighLevel](/guides/send-imessage-from-gohighlevel). **3. You need both** They coexist. Messages for Business handles inbound support; a Tuco line handles outbound follow-up. ## Getting started with the API side Check availability, then send. Both are single calls — see [Check iMessage availability](/features/check-availability) and [Send messages](/features/send-messages), or the [API reference](/api-reference/introduction). Non-iMessage contacts come back as `fallback` so you can route them to SMS: [Failures, fallbacks and delivery outcomes](/features/failures-and-fallbacks). ## Related * [Does iMessage need A2P 10DLC registration?](/guides/imessage-a2p-10dlc-carrier-filtering) * [iMessage vs SMS for sales](/guides/imessage-vs-sms-for-sales) * [Automate iMessage sales outreach](/guides/automate-imessage-sales-outreach) # How to Automate iMessage for Sales Outreach Source: https://docs.tuco.ai/guides/automate-imessage-sales-outreach Automate iMessage sales outreach with Tuco AI — verify availability, send personalized blue-bubble messages, auto-reply, and fall back to SMS. **To automate iMessage for sales, you connect an Apple-signed-in sending line to an automation platform like Tuco AI, verify which contacts can receive iMessage, then send personalized blue-bubble messages on a schedule with automatic SMS fallback and AI-assisted replies.** iMessage can't be automated from a CRM directly because it runs only through Apple's network — Tuco provides the sending lines and the sending engine, and connects to HubSpot and GoHighLevel so your CRM stays the source of truth. > [!WARNING] > > **iMessage should be triggered, not blasted.** Automating iMessage means firing a personalized message off an event — a new lead, a reply, a form fill, or a CRM stage change — one contact at a time, within per-line rate limits. It does **not** mean spraying an identical message to a big static list; that behavior gets iMessage lines flagged and banned by Apple. ## What iMessage automation includes | Capability | What it does | | - | - | | Availability checking | Verifies whether each contact can receive iMessage before sending. See [check availability](/guides/check-imessage-availability). | | Personalized sending | Sends blue-bubble iMessage with merge variables, immediately or scheduled. | | Follow-ups | Multi-step follow-ups sent from your [GoHighLevel](/integrations/ghl) (or CRM) workflows, within per-line rate limits. | | SMS fallback | Routes non-iMessage contacts to SMS automatically so nothing is dropped. | | Replies & AI responder | Ingests inbound replies and can auto-reply from your knowledge base. | | CRM sync | Two-way with HubSpot and GoHighLevel, deduped by phone. | ## Set up automated iMessage outreach in 5 steps **1. Connect a sending line and your CRM** Add an Apple-connected line, then connect [HubSpot](/guides/send-imessage-from-hubspot) or [GoHighLevel](/guides/send-imessage-from-gohighlevel). Contacts sync in and dedupe by phone. **2. Verify iMessage availability** Tuco checks every lead automatically, so eligible contacts get iMessage and the rest are flagged for SMS. **3. Send and follow up** [Send messages](/features/send-messages) with personalization, immediately or scheduled, and send follow-ups from a [GoHighLevel](/integrations/ghl) (or your CRM) workflow. Respect [rate limits](/features/rate-limits) to protect deliverability. **4. Set your fallback and compliance rules** Configure your SMS fallback and opt-out handling so every contact is reachable and every STOP is honored. See [compliance & opt-outs](/guides/imessage-compliance-tcpa). **5. Automate replies** Turn on the AI responder / [knowledge base](/features/knowledge-base) so common replies are answered instantly, and route the rest to a rep. ## Why not just use SMS? iMessage sends as a blue bubble over Apple's data network with delivery and (optionally) read receipts, typing indicators, reactions, and native voice notes — signals plain SMS doesn't carry. For a channel-by-channel comparison, see [iMessage vs SMS for sales](/guides/imessage-vs-sms-for-sales). ## Frequently asked questions > [accordion] Can you automate iMessage? > > Yes — through an Apple-connected sending line and an automation layer like Tuco AI. You can't automate iMessage directly from a CRM because iMessage only runs on Apple's network, so Tuco bridges the two. > [accordion] Do recipients need iPhones? > > To receive a blue-bubble iMessage, yes — the recipient must have iMessage enabled on an Apple device. Tuco checks this first and sends non-iMessage contacts over SMS instead. > [accordion] Does it work with my CRM? > > Tuco has native two-way integrations with HubSpot and GoHighLevel, plus a REST API, webhooks, and an MCP server for other tools. > [accordion] How do I keep outreach compliant? > > Collect consent, identify yourself, and honor opt-outs (STOP / UNSUBSCRIBE) on every channel. See the [compliance guide](/guides/imessage-compliance-tcpa). > [card] [Send from HubSpot](/guides/send-imessage-from-hubspot) > > Connect HubSpot and send iMessage in minutes. > [card] [Send from GoHighLevel](/guides/send-imessage-from-gohighlevel) > > Trigger iMessage from any GHL workflow. # Best iMessage Automation Tools for Business (2026) Source: https://docs.tuco.ai/guides/best-imessage-automation-tools Compare the best iMessage automation tools for business in 2026 — Tuco AI, Sendblue, LoopMessage, Blooio — and which send true blue-bubble iMessage. **The best iMessage automation tool depends on your stack: for CRM-native outreach from HubSpot or GoHighLevel with iMessage-availability checking and AI replies, Tuco AI is purpose-built; for a raw developer iMessage API, Sendblue and LoopMessage are the established options; and several "business texting" platforms (Salesmsg, OpenPhone) only send SMS, not true blue-bubble iMessage.** The most important thing to verify first is whether a tool sends *actual iMessage* (blue bubble, over Apple's network) or just SMS. ## How to choose an iMessage automation tool * **True iMessage vs SMS** — confirm it sends blue-bubble iMessage, not just green-bubble SMS. * **CRM integration** — native HubSpot / GoHighLevel / Salesforce support vs a bare API you have to wire up. * **Availability checking** — does it verify a contact is on iMessage *before* sending? * **Fallback** — does it route non-iMessage contacts to SMS automatically? * **Replies & AI** — inbound reply handling and auto-responders for scale. * **Compliance** — consent tracking and opt-out (STOP) handling. ## iMessage & business-texting tools compared | Tool | What it does | Sends true iMessage? | | - | - | - | | **Tuco AI** | CRM-native iMessage automation for HubSpot & GoHighLevel; verifies iMessage availability before sending, AI reply responder, native voice notes, SMS fallback | Yes (blue bubble) | | **Sendblue** | Established iMessage API for developers; REST, webhooks, SDKs, broadcast tooling | Yes (blue bubble) | | **LoopMessage** | iMessage API popular for bot/ChatGPT-to-iMessage use; self-managed warm-up | Yes (blue bubble) | | **Blooio** | Flat-price iMessage platform with GoHighLevel and n8n integrations | Yes (blue bubble) | | **iBluSend** | iMessage-for-CRM platform (GHL, HubSpot) with workflow actions and voice notes | Yes (blue bubble) | | **BlueBubbles** | Open-source, self-hosted macOS server that bridges iMessage; the underlying tech many tools build on | Yes (self-hosted) | | **Salesmsg** | Business texting/calling with deep HubSpot & Salesforce integration | SMS only | | **OpenPhone (Quo)** | Business phone with shared inboxes, texting, and AI | SMS only | | **Twilio / Vonage / Telnyx** | Mature SMS/MMS/RCS APIs for developers | No iMessage | | **Apple Messages for Business** | Apple's official, customer-initiated support channel (requires human escalation) | Official Apple, not an outbound-blast tool | > [!NOTE] > > Tool capabilities and pricing change frequently — verify current features on each vendor's site before deciding. Descriptions here reflect each tool's stated positioning at time of writing. ## Where Tuco AI fits Tuco is built for teams that run outreach **from their CRM** and want iMessage without leaving HubSpot or GoHighLevel: * Verifies [iMessage availability](/guides/check-imessage-availability) on every contact and falls back to SMS automatically. * Sends from [HubSpot](/guides/send-imessage-from-hubspot) and [GoHighLevel](/guides/send-imessage-from-gohighlevel) with native sync and workflow actions. * Handles replies with an AI responder backed by your [knowledge base](/features/knowledge-base). * Sends native iMessage voice notes and enforces per-line rate limits. ## Frequently asked questions > [accordion] What is the best iMessage API for business? > > For a developer-first iMessage API, Sendblue and LoopMessage are the established choices. For CRM-native automation from HubSpot or GoHighLevel with availability checking and AI replies built in, Tuco AI is purpose-built. Match the tool to whether you need a raw API or an end-to-end CRM workflow. > [accordion] Which business texting tools actually send iMessage? > > Tuco AI, Sendblue, LoopMessage, Blooio, iBluSend, and self-hosted BlueBubbles send true blue-bubble iMessage. Salesmsg and OpenPhone are SMS-only, and Twilio/Vonage/Telnyx are SMS/MMS/RCS APIs without iMessage. > [accordion] Do I need a Mac to automate iMessage? > > iMessage runs only on Apple's network, so every iMessage tool relies on Apple-signed-in infrastructure somewhere. Hosted platforms like Tuco manage that for you, whereas self-hosted BlueBubbles requires you to run your own Mac server. > [accordion] What should I check before buying? > > Confirm it sends true iMessage (not SMS), integrates with your CRM, checks availability before sending, falls back to SMS, handles replies, and supports consent/opt-out compliance. > [card] [See how Tuco automates iMessage](/guides/automate-imessage-sales-outreach) > > iMessage-first outreach from your CRM, with availability checks and SMS fallback. # How to Check if a Phone Number Has iMessage Source: https://docs.tuco.ai/guides/check-imessage-availability Check whether a phone number or email can receive iMessage before you text. Tuco AI verifies Apple iMessage availability automatically before every send. **To check if a phone number has iMessage, verify whether that number (or email) is registered with Apple's iMessage service before you send — Tuco AI does this automatically for every lead and returns a clear status: blue-bubble available, or SMS/email only.** Sending to a number that isn't on iMessage wastes the blue-bubble channel and can cause delivery failures, so availability checking is the first step in any iMessage outreach. ## What "iMessage availability" means A phone number or email is "on iMessage" when it's registered as an Apple ID iMessage endpoint — i.e. an active Apple device is signed in and set to receive iMessage at that address. If it is, messages arrive as blue bubbles over Apple's network; if not, they can only be reached by SMS (green bubble) or email. ## How Tuco checks availability Tuco checks each contact's addresses in priority order and stops at the first one that supports iMessage: 1. Primary phone 2. Primary email 3. Alternate phones 4. Alternate emails **1. Automatic on upload** When you upload or sync leads (from CSV, HubSpot, or GoHighLevel), Tuco automatically checks all phone and email addresses and stamps each lead with an availability status. **2. Manual re-check** Re-check a single lead or a bulk selection any time from the **Leads** page — availability changes when a contact enables or disables iMessage on their device. **3. Live preview in Quick Send** When composing a Quick Send, Tuco checks the recipient as you type (500 ms debounce) and shows the availability icon inline. ### Status indicators | Icon | Status | Meaning | | - | - | - | | 🔵 | Available | Supports iMessage (blue bubble) | | ⚪ | Unavailable | SMS / email only | | 🔄 | Checking | Verification in progress | | ⚠️ | Error | Check failed — retry available | ## How many numbers can I check? Each Tuco line performs up to **70 iMessage availability checks per day**. With multiple lines, checks are distributed across them automatically, so more lines means more daily checks. Bulk checks are processed sequentially, so large batches can take a few minutes. ## Why check before sending * **Higher deliverability** — route each contact through the channel that actually works. * **No wasted blue-bubble sends** — avoid failures from texting numbers not on iMessage. * **Automatic fallback** — contacts who aren't on iMessage are sent via SMS instead, so nothing is dropped. ## Frequently asked questions > [accordion] Can you tell if someone has iMessage without texting them? > > Yes. Tuco checks whether a number or email is registered with Apple's iMessage service and returns the result without sending a message — it happens automatically on upload and on demand. > [accordion] Does an email address work for iMessage? > > Yes. An Apple ID email can be an iMessage endpoint. Tuco checks both phone numbers and emails, and uses whichever supports iMessage first. > [accordion] Why did a contact's availability change? > > Availability reflects the contact's current device settings. Someone can enable or disable iMessage, or switch devices, so re-check periodically before major sends. > [accordion] What happens to contacts who aren't on iMessage? > > Tuco routes them to your configured SMS fallback automatically, so they still receive the message over a channel that works. > [card] [Availability feature reference](/features/check-availability) > > The full availability system: statuses, bulk checks, API, and check priority. # Does iMessage Need A2P 10DLC Registration? Source: https://docs.tuco.ai/guides/imessage-a2p-10dlc-carrier-filtering No. iMessage is not carrier SMS, so A2P 10DLC and carrier filtering don't apply. Reaching Android doesn't need it either when the line sends the SMS itself. **No. iMessage does not require A2P 10DLC registration, because iMessage is not carrier SMS — it travels over Apple's network, not the US carrier A2P pipeline, so 10DLC brand/campaign registration and carrier content filtering do not apply to it.** Reaching **Android** does not require it either, as long as the line sends the SMS itself. With [P2P SMS](/guides/reach-android-contacts-p2p-sms) the text goes out from the line's own number through the iPhone paired to it — person-to-person traffic, which the A2P programme does not cover. A2P 10DLC only enters the picture if you route Android through a **separate SMS provider** you own (Twilio, Telnyx, GoHighLevel). That is genuinely application-to-person, and US carriers require registration for it. ## The split in one table | | iMessage (blue bubble) | P2P SMS from the line (green bubble) | SMS via your own provider | | - | - | - | - | | Network | Apple, over data | US carriers, person-to-person | US carriers, application-to-person | | A2P 10DLC brand + campaign registration | Not applicable | **Not required** | **Required** | | Carrier content filtering / "spam likely" | Not applicable | Ordinary P2P treatment | Applies | | Who provides the number | Tuco line on dedicated Apple hardware | The **same** Tuco line | A number you bring and register | | What the contact sees | Blue bubble | Green bubble, **same number and thread** | A different number | | Time to start sending | \~48h for line activation | Enabled per line by support | Registration timeline is set by the carriers | ## Why A2P 10DLC does not reach iMessage A2P 10DLC is a US carrier programme. It governs application-to-person traffic sent over the carriers' SMS network from 10-digit long codes: you register a brand, register a campaign, get throughput assigned, and carriers filter what does not match. Every one of those steps is a carrier step. iMessage never enters that pipeline. A message between two Apple devices is routed by Apple over data. There is no carrier campaign to register against it, no 10DLC throughput tier, and no carrier content filter in the path. This is why "spam likely" labelling — a carrier-side reputation signal on voice and SMS — has no iMessage equivalent. > [!WARNING] > > Not needing A2P registration is not the same as not needing consent. TCPA, GDPR and Apple's own terms still apply to every message you send. See [iMessage compliance and TCPA](/guides/imessage-compliance-tcpa). ## What this means in practice **1. Tuco checks availability before it sends** Every address is checked for iMessage capability first, so a contact is only routed to SMS when iMessage genuinely is not available. See [Check iMessage availability](/features/check-availability). **2. iPhone contacts need no registration** They receive iMessage from your dedicated Tuco line. No brand registration, no campaign, no carrier filter. **3. Android contacts can be reached without any registration** Turn on **P2P SMS** for the line and it texts them itself, from its own number — no brand, no campaign, no A2P. It is off by default; ask support to enable it. See [Reach Android contacts](/guides/reach-android-contacts-p2p-sms). **4. Or route Android through your own provider** Connect Twilio, Telnyx or GoHighLevel under **Settings → When iMessage isn't available**. This route *is* application-to-person, so US traffic needs A2P 10DLC registration. **5. Or send to iPhone contacts only** With neither enabled, Tuco marks non-iMessage recipients as `fallback` and nothing is sent — see [Failures, fallbacks and delivery outcomes](/features/failures-and-fallbacks). ## What still limits your sending A2P throughput tiers do not apply, but Tuco's own per-line pacing does. Per line that is **50 new-contact sends per day** (the maximum), **150 total sends per day** by default (raisable in Lines → Edit, but that voids the free first replacement), and new contacts paced at **up to 49 per hour** so a line never bursts. Adding lines multiplies capacity. See [rate limits](/features/rate-limits) and [limits](/limits). ## Related * [Check iMessage availability](/features/check-availability) — route before you send * [Failures, fallbacks and delivery outcomes](/features/failures-and-fallbacks) — what `fallback` means * [iMessage compliance and TCPA](/guides/imessage-compliance-tcpa) — consent, opt-outs * [Send bulk iMessage](/guides/send-bulk-imessage) — pacing at volume # Is iMessage Marketing Legal? TCPA & Consent Rules Source: https://docs.tuco.ai/guides/imessage-compliance-tcpa Is iMessage marketing legal? Under TCPA yes — get consent, honor opt-outs, respect quiet hours. How Tuco AI helps you run compliant iMessage outreach. **Automated iMessage and SMS outreach is legal in the United States as long as you follow the TCPA: get prior express written consent before sending marketing texts, identify yourself, honor opt-outs immediately, and only send during allowed hours.** This page describes implementation patterns, not legal advice — always confirm specifics with your own counsel. Tuco AI gives you the primitives (consent fields, opt-out detection, suppression, message logs) to build a compliant program; how you use them is your responsibility. ## US TCPA requirements at a glance These are the widely-reported baseline rules for marketing text messages in the US. Requirements vary by jurisdiction and change over time. | Requirement | What it means | | - | - | | **Prior express written consent (PEWC)** | Get documented opt-in before sending marketing texts, with a "consent is not a condition of purchase" disclosure. | | **Quiet hours** | Don't send marketing texts before 8 AM or after 9 PM in the **recipient's** local time zone. | | **Honor opt-outs** | Stop promptly when someone replies STOP / UNSUBSCRIBE / REMOVE. | | **Sender identity** | Clearly identify who is messaging. | | **Damages** | TCPA statutory damages are commonly cited at **$500–$1,500 per violating message** — treat compliance as non-optional. | ## How Tuco helps you stay compliant **1. Track consent on the lead** Store consent attributes on each lead (e.g. `hasConsentedToMessaging`, `consentSource`, `consentTimestamp`) and filter your audience to consented contacts before you send. **2. Detect and honor opt-outs** Tuco ingests inbound replies and surfaces them in the inbox and via webhooks. Classify STOP-type replies, set opt-out flags, and exclude those contacts from future sends. **3. Suppress and exclude** Maintain global suppression lists so you never contact opted-out or do-not-contact addresses. See [DNC handling](/features/dnc). **4. Keep records** Use Tuco's message and webhook history as evidence of what was sent and when, correlated with your own consent records. See the full [compliance & opt-outs](/features/compliance-and-optouts) and [anti-spam guidelines](/features/anti-spam-guidelines) references. ## Is automated iMessage against Apple's rules? Apple's officially sanctioned business channel is **Apple Messages for Business**, which is designed for customer-initiated conversations and requires a human escalation path — it is not an outbound marketing-blast tool. Tuco is built for reaching your **own consented contacts** with identified, opt-out-respecting outreach. Keep your audiences opt-in, honor every STOP, and don't message people who never agreed to hear from you. ## Frequently asked questions > [accordion] Is it legal to send marketing texts over iMessage? > > Yes, in the US, when you comply with the TCPA — prior express written consent, clear sender identity, honored opt-outs, and allowed sending hours. The same rules that govern SMS marketing apply to iMessage marketing. > [accordion] Does the TCPA apply to iMessage? > > The TCPA governs marketing "calls" and text messages to mobile numbers. Treat iMessage marketing the same as SMS marketing for consent, opt-out, and timing purposes, and consult counsel for your specifics. > [accordion] How do opt-outs work in Tuco? > > Replies are ingested and available in the inbox and via webhooks. You classify opt-out language (STOP, UNSUBSCRIBE, REMOVE), flag the lead, and future sends exclude them. Set up suppression lists so opted-out contacts are never re-added. > [accordion] What are texting quiet hours? > > A common TCPA guideline is no marketing texts before 8 AM or after 9 PM in the recipient's local time zone. Schedule sends with the recipient's time zone in mind. > [accordion] Does Tuco give legal advice? > > No. Tuco provides compliance primitives — consent fields, opt-out detection, suppression, and audit logs. You are responsible for how you collect consent and design your outreach; consult your legal counsel. > [card] [Compliance & opt-outs reference](/features/compliance-and-optouts) > > Consent storage, opt-out patterns, suppression, and record-keeping in detail. # iMessage Delivery: Sent vs Delivered vs Read Source: https://docs.tuco.ai/guides/imessage-delivery-and-read-receipts What each Tuco message status actually proves, why sent is not delivered, and why read receipts are a floor rather than an exact count. **`sent` means Tuco handed the message to the channel. `delivered` means the channel confirmed it reached the device. They are different guarantees, and a message can sit at `sent` forever without ever being `delivered`.** Read receipts are a further step again: they only exist when the recipient has read receipts switched on, so treat them as a floor on how many people read you, never as an exact count. ## The statuses you can build on | Status | What it proves | What it does not prove | | - | - | - | | `queued` | The send is planned but not yet eligible — waiting on allowed hours, line capacity, or a scheduled send time | Nothing has left Tuco | | `pending` / `sending` | Actively in flight | — | | `sent` | Tuco handed the message to the channel per that channel's contract | That any device received it | | `delivered` | The channel confirmed it reached the recipient's device or mailbox | That a human saw it | | `failed` | Tuco determined the message cannot be sent. Not silently retried | — | | `fallback` | The primary channel is unavailable for this recipient — typically no iMessage-capable address | That the contact is unreachable; your SMS fallback may still reach them | Full detail: [Failures, fallbacks and delivery outcomes](/features/failures-and-fallbacks). ## Why sent is not delivered `sent` is a statement about Tuco's side of the boundary: the message was accepted by the channel. Everything after that is outside Tuco's control — the device may be off, the number may no longer be in use, the recipient may have blocked the sender, or the message may have been downgraded at the carrier on the SMS leg. If a message shows `sent` but the lead says nothing arrived, the problem is downstream. Work through [Message not received](/troubleshooting/message-not-received) and [Sent vs Delivered](/troubleshooting/message-statuses). ## Why read receipts undercount A read receipt only exists if the recipient has read receipts enabled on their device. Many people do not. So: > [!WARNING] > > Read rate is a **floor**, not a measurement. A 40% read rate means at least 40% read it — not that 60% did not. Never report read receipts as an engagement ceiling, and never compare read rate across audiences with different device settings. The metric that survives this problem is **reply rate against contacts you actually reached**: `replied / reached`, where `reached` counts distinct recipients a message actually got to. That is comparable across workspaces regardless of how iMessage delivery landed. See [the analytics API](/api-reference/endpoint/analytics-insights) for the `insights.unique` breakdown. ## Building automations on outcomes **1. Trigger on sent for internal bookkeeping** Activity feeds, CRM timeline entries, "message went out" notifications. **2. Trigger on delivered for time-based follow-up** Waiting "3 days after delivery" is only meaningful once delivery is confirmed. **3. Trigger on fallback to switch channel** Route to SMS or email, or tag the lead as not reachable on iMessage. **4. Alert on failed rates, not individual failures** A single failure is data hygiene. A rising failure rate on one line is an operational signal. Webhooks fire on these transitions — see [message webhooks](/api-reference/message-webhooks). ## Related * [Check iMessage availability](/features/check-availability) — avoid failures before they happen * [Does iMessage need A2P 10DLC registration?](/guides/imessage-a2p-10dlc-carrier-filtering) * [Send bulk iMessage](/guides/send-bulk-imessage) — pacing and caps # iMessage vs SMS for Sales Outreach Source: https://docs.tuco.ai/guides/imessage-vs-sms-for-sales iMessage vs SMS for sales: iMessage adds read receipts and richer media but reaches only Apple devices; SMS reaches everyone. Use both with Tuco AI. **For sales outreach, iMessage offers richer signals than SMS — native delivery and read receipts, typing indicators, reactions, and high-quality media over Apple's data network — but it only reaches people on Apple devices, so the strongest strategy is to send iMessage where it's available and fall back to SMS for everyone else.** Tuco AI does exactly that: it checks iMessage availability per contact, sends blue-bubble iMessage when possible, and routes the rest to SMS automatically. ## Side-by-side comparison | | iMessage (blue bubble) | SMS (green bubble) | | - | - | - | | Network | Apple's data network | Carrier network | | Reaches | Apple devices with iMessage enabled | Any mobile phone | | Delivery receipt | Yes, native | No business-visible receipt | | Read receipts | Yes (if recipient enables) | No | | Typing indicators / reactions | Yes | No | | Media | High-quality images, video, native voice notes | MMS (lower quality, size limits) | | US A2P 10DLC registration | Not required (runs over Apple, not carrier A2P) | Required for A2P sending | ## What the response-rate claims actually say iMessage vendors commonly report **much higher open and response rates for iMessage than SMS** — figures like "\~3–5× the response rate" appear across the industry. Treat these as **provider-reported marketing figures**, not independently audited statistics. One nuance worth knowing: the widely-quoted "SMS has a \~98% open rate" number is really a **delivery-rate estimate** — SMS has no true, measurable read receipt, so no platform can actually measure SMS "opens." iMessage, by contrast, exposes native read receipts when the recipient has them enabled, which is one reason it gives sales teams clearer engagement signals. ## When to use which * **Use iMessage** for higher-touch outreach where read receipts, reactions, and voice notes improve the conversation — and for contacts you've verified are on iMessage. * **Use SMS** as the universal fallback so contacts on Android or without iMessage still get the message. * **Use both, automatically** — let Tuco verify [iMessage availability](/guides/check-imessage-availability) per contact and pick the channel, with [SMS fallback](/features/failures-and-fallbacks) built in. ## Frequently asked questions > [accordion] Is iMessage better than SMS for business texting? > > iMessage gives richer engagement signals (delivery and read receipts, typing indicators, reactions, better media) but only reaches Apple devices. SMS reaches every phone. The best results come from using iMessage where available and SMS as fallback — which Tuco automates. > [accordion] Why do iMessages seem to get more replies than SMS? > > Providers attribute it to the richer, more personal feel of blue-bubble threads and to visible read receipts that let reps time follow-ups. These are vendor-reported figures, so validate against your own results. > [accordion] Does iMessage need 10DLC registration like SMS? > > No. US A2P SMS requires 10DLC brand/campaign registration because it runs over carrier networks. iMessage runs over Apple's network and isn't part of the carrier A2P system. You still must follow consent and opt-out rules — see the [compliance guide](/guides/imessage-compliance-tcpa). > [accordion] What happens when a contact isn't on iMessage? > > Tuco detects it during the availability check and sends that contact over SMS instead, so nobody is missed regardless of device. > [card] [Automate both channels](/guides/automate-imessage-sales-outreach) > > Set up iMessage-first outreach with automatic SMS fallback. # Reach Android Contacts Without A2P (P2P SMS) Source: https://docs.tuco.ai/guides/reach-android-contacts-p2p-sms Turn on P2P SMS and a Tuco line texts Android contacts from its own number — green bubble, same thread, no A2P 10DLC registration. Off by default. **A Tuco line can send an ordinary text message itself, from its own number, to a contact who isn't on iMessage.** Same number, same thread — the contact just sees a green bubble instead of a blue one. Because it's person-to-person traffic, there is **no A2P 10DLC brand or campaign registration**. > [!NOTE] > > P2P SMS is **off by default on every line**. It is enabled per line by Tuco support — there is no self-serve toggle. Ask us to turn it on for the lines you want it on. > [!NOTE] > > P2P SMS only reaches recipients **in the country of the line's eSIM** — a US eSIM texts US numbers, a Canadian eSIM texts Canadian numbers. iMessage itself works globally. ## Why this isn't A2P A2P 10DLC governs *application-to-person* traffic: software sending from a 10-digit long code you registered with the carriers. P2P SMS is the opposite shape. The message leaves the iPhone paired to your line's Mac, over that phone's own carrier plan, the way a person's phone sends a text. There's no long code to register and no campaign to file. That also means there's **no second number**. No Twilio, no Telnyx, no separate sender. If a contact replies, it lands in the same conversation as everything else. ## What you get | | Without P2P SMS | With P2P SMS | | - | - | - | | iPhone contact | iMessage | iMessage — unchanged | | Android contact, no SMS provider connected | **Not reached** | Green-bubble text from the same line | | Android contact, provider connected | Text from your provider's number | Green-bubble text from the **line's** number | | A2P 10DLC registration | Required for the provider route | **Not required** | ## The order Tuco uses When a contact turns out not to be on iMessage: **1. The line's own SMS, if it's enabled** Sent as a green bubble from the same number. This wins even when you have an SMS provider connected — the contact's existing thread beats a number they don't recognise. **2. Your SMS provider, if one is configured** Twilio, Telnyx or GoHighLevel, from a separate number. This route needs A2P 10DLC. **3. Otherwise, nothing is sent** The message is marked **No iMessage — not reached** so you can see it plainly rather than assuming it landed. ## What it looks like in the Unibox A green send shows as **Sent as SMS**. It sits in the same conversation as the iMessages, because it came from the same number. A message that could not be delivered any way shows **No iMessage — not reached** — that label means nothing went out, not that a text was sent. ## Requirements and limits > [accordion] What has to be true for a green send to work > > * P2P SMS enabled on the line (support does this) > * The paired iPhone online, with **Text Message Forwarding** on for that Mac > * The line healthy — a green text leaves the same Mac as an iMessage, so a line that's down can't send either > * A valid mobile number. An Apple ID email can't receive a text. > [accordion] Text only — no images, files or voice notes > > Attachments over green would be MMS, which is a different path and isn't supported. A message with an attachment won't green-send; it falls through to your provider, or is marked not reached. > [accordion] Does it use up my line's sending limits? > > Yes. A green text leaves the same Mac and the same Messages app as an iMessage, so Apple sees it the same way and it counts against the same per-line caps. See [rate limits](/features/rate-limits). > [accordion] Do delivery receipts work? > > No. SMS carries no delivery or read receipts, so a green send shows as **Sent as SMS** and stops there. That is the transport, not a problem with the message. > [accordion] Does consent still apply? > > Yes, exactly as before. Skipping A2P registration is not skipping consent — TCPA, GDPR and Apple's terms all still apply. See [iMessage compliance and TCPA](/guides/imessage-compliance-tcpa). > [card] [Does iMessage need A2P 10DLC registration?](/guides/imessage-a2p-10dlc-carrier-filtering) > > The full split between iMessage, P2P SMS and provider SMS — and which of them the carriers actually regulate. # Bulk iMessage: How to Message a List Without Getting Banned Source: https://docs.tuco.ai/guides/send-bulk-imessage Can you send bulk iMessage? Tuco AI sends to a lead list as personalized 1:1 messages within per-line daily limits — not spam blasts that get lines banned. **Tuco AI is not a mass-blast tool, by design.** You can message an entire lead list, but every contact receives an **individual, personalized iMessage** sent within strict **per-line daily limits** — because blasting identical messages from one line is the fastest way to get it flagged or banned by Apple. If you're looking to spray thousands of identical texts, Tuco is the wrong tool. If you want to reach a list the way that actually lands and keeps your line healthy, here's how. > [!WARNING] > > **iMessage should be triggered, not blasted.** The safe, effective pattern is a personalized message **fired by an event** — a new lead, a form submission, a reply, or a CRM stage change — sent one contact at a time from your workflow. Batch-spraying identical messages to a static list is what gets iMessage lines flagged and banned by Apple. Whenever possible, [trigger sends from a HubSpot or GoHighLevel workflow](/guides/send-imessage-from-gohighlevel) instead of uploading a list to push out at once. ## Why "blasting" iMessage doesn't work Apple aggressively flags accounts that behave like spam senders. Identical messages fired at high volume from a cold line get rate-limited, then banned — taking your conversations with it. Tuco deliberately caps every line and requires warm-up ([rate limits](/features/rate-limits), [anti-spam guidelines](/features/anti-spam-guidelines)) so one over-eager send can't destroy your line's reputation. Volume comes from **more warmed-up lines sending personalized messages**, not from blasting a single line. ## Message a lead list the right way — 4 steps **1. Import your list** Upload a [CSV or Google Sheet](/features/upload-leads), or sync from [HubSpot](/guides/send-imessage-from-hubspot) / [GoHighLevel](/guides/send-imessage-from-gohighlevel). Contacts are validated and deduplicated by phone number on import. **2. Verify availability** Tuco checks [iMessage availability](/guides/check-imessage-availability) across the list so eligible contacts get blue-bubble iMessage and the rest fall back to SMS. **3. Personalize every message** [Send to your leads](/features/send-messages#send-to-leads) with merge variables so each contact gets a genuinely individual message — not an identical blast. Personalization is what makes list outreach both effective and safe. **4. Send within limits, with fallback** Tuco paces sends inside your [per-line rate limits](/features/rate-limits) and routes non-iMessage contacts to [SMS fallback](/features/failures-and-fallbacks), so the list is reached without risking your lines. ## How much can I actually send? Daily send volume is **deliberately capped per line** and scales with your plan and number of lines (see [pricing](/pricing)) — not unlimited. Each line also performs up to **70 iMessage availability checks per day**. New lines should **warm up gradually** rather than start at the cap. These limits exist to protect your deliverability, and they apply to every send path (Quick Send, dashboard, HubSpot/GHL plugins, and the API). ## Do it safely * **Personalize** — individual messages, never identical blasts. * **Warm up new lines** — ramp volume gradually. * **Verify availability first** — don't waste sends on non-iMessage numbers. * **Get consent and honor opt-outs** — process STOP immediately (see [compliance](/guides/imessage-compliance-tcpa)). * **Add lines to scale** — spread volume rather than overloading one line. ## Frequently asked questions > [accordion] Can you blast mass iMessage from a spreadsheet? > > No — Tuco is not a spam-blast tool. You can import a list and message it, but sends are personalized per contact and capped per line to protect deliverability. Firing identical bulk messages is exactly what gets iMessage lines banned. > [accordion] How do I message a large list without getting flagged? > > Personalize every message, warm up new lines, stay within your per-line daily limits, verify iMessage availability first, and honor opt-outs. Scale by adding warmed-up lines — not by pushing one line harder. > [accordion] How many iMessages can I send per day? > > It's capped per line and scales with your plan and line count (see [pricing](/pricing)) — intentionally limited to keep your lines healthy. Tuco enforces these caps across every send path. > [accordion] Does this require 10DLC registration? > > No. iMessage runs over Apple's network, not the carrier A2P system that requires 10DLC. You still must follow consent and opt-out rules — see the [compliance guide](/guides/imessage-compliance-tcpa). > [card] [Upload your leads](/features/upload-leads) > > Import from CSV, Google Sheets, HubSpot, or GoHighLevel to start personalized list outreach. # How to Send iMessage from Customer.io Source: https://docs.tuco.ai/guides/send-imessage-from-customer-io Send 1:1 iMessage from a Customer.io journey with a Webhook action, and record Tuco replies, sends and failures back on the person as Customer.io events. **You send iMessage from Customer.io with a journey Webhook action that POSTs to `https://app.tuco.ai/api/messages` with your Tuco API key, and you get replies back by pointing Tuco's message webhooks at a webhook-triggered Customer.io journey.** Customer.io has no native iMessage channel. Tuco sends from a dedicated line and fires `message.sent`, `message.reply`, `message.fallback` and `message.failed`, which Customer.io records as events on the person. No Zapier or n8n is needed in between. Overview, architecture and FAQ: [tuco.ai/integrations/customer-io](https://tuco.ai/integrations/customer-io). ## Journey 1 — send the message Create an **event-triggered** journey on your opt-in event (for example `form_submitted`). Add a **Webhook** action: **1. Request** Method `POST`, URL `https://app.tuco.ai/api/messages`. **2. Headers** `Authorization: Bearer tuco_xxxxxxxxxxxxx` ([API key](/api-reference/api-keys)), `Content-Type: application/json`, and optionally `Idempotency-Key: cio-{{customer.id}}-first` so a Customer.io retry never sends twice. **3. Body** Paste the JSON below. Customer.io fills in the Liquid from the profile. ```json theme={null} { "message": "{% if customer.first_name != blank %}Hi {{customer.first_name}}{% else %}Hi there{% endif %}, thanks for reaching out. Any questions I can answer for you here?", "recipientPhone": "{{customer.phone}}", "recipientEmail": "{{customer.email}}", "recipientName": "{{customer.first_name}} {{customer.last_name}}", "contactOwnerEmail": "{{customer.owner_email}}", "sendWindowStart": "09:00", "sendWindowEnd": "20:00", "timezone": "{{customer.timezone | default: 'America/New_York'}}", "skipIfReplied": true } ``` * **`recipientEmail` links replies to the person.** Tuco texts `recipientPhone` first and stores the email on its lead. Every webhook then carries `lead.email`, which Journey 2 uses to find the Customer.io profile. * **`contactOwnerEmail`** assigns the conversation to a rep. Reply notifications go to that person only. * **Send window:** outside 09:00–20:00 in the contact's timezone, the request still returns `201` with `status: "scheduled"`, and Tuco sends when the window opens. * **First message = plain text.** Links aren't clickable and attachments are dropped on a first-ever message ([limits](/limits)). Put links and media in a later step. * **Never send an empty greeting.** A body like `"Hi , …"` or one still containing `{{firstName}}` is rejected with `400 MALFORMED_NAME_TEMPLATE`. The `{% if %}` above prevents it. For a follow-up, add a delay and a second Webhook action with the same body plus `"respectGap": true`. With `skipIfReplied: true`, Tuco returns `200` with `skippedOnly: true` and sends nothing if the contact has already replied. See [Send Message](/api-reference/endpoint/send-message) for every field. ## Journey 2 — get replies back into Customer.io **1. Create a webhook-triggered journey** In Customer.io, create a journey with a **Webhook** trigger and copy its incoming URL. **2. Add a Create Event action** Identify the person by **email** = `{{trigger.lead.email}}`. Event name (Liquid): `tuco_{{ trigger.event | replace: '.', '_' }}`. **3. Map attributes** `text`, `tuco_message_id` = `{{trigger.messageId}}`, `tuco_lead_id` = `{{trigger.leadId}}`, `phone` = `{{trigger.lead.phone}}`, `occurred_at` = `{{trigger.timestamp}}`. **4. Register it in Tuco** Add the URL under **Integrations → Webhooks** (or [Create Webhook](/api-reference/endpoint/create-webhook)) and subscribe to `message.sent`, `message.reply`, `message.fallback`, `message.failed` and `conversation.handover`. Use **Send test** to confirm delivery. > [!WARNING] > > `message` is a **string** (the reply text) on `message.reply`, and the **full message object** on sent, failed and fallback. Map `text` with a branch: > > `{% if trigger.event == 'message.reply' %}{{trigger.message}}{% else %}{{trigger.message.message}}{% endif %}` | Tuco webhook | Customer.io event | Typical use | | - | - | - | | `message.sent` | `tuco_message_sent` | Mark the step done | | `message.reply` | `tuco_message_reply` | Exit nurture journeys, alert the owner, branch on the text | | `message.fallback` | `tuco_message_fallback` | No iMessage on the number: send SMS or email from Customer.io | | `message.failed` | `tuco_message_failed` | Alert ops, retry on another channel | | `conversation.handover` | `tuco_conversation_handover` | AI responder handed off to a person | Payload shapes for each event: [Message Webhooks](/api-reference/message-webhooks). ## Test before you start the journeys 1. Trigger the opt-in event for a test profile with your own mobile number. 2. Confirm the iMessage arrives, then reply to it. 3. Check the profile's activity log for `tuco_message_reply`. 4. If nothing arrives, open the webhook action's delivery in Customer.io. The response body names the reason, for example `INVALID_TIMEZONE`, a daily cap, or `MALFORMED_NAME_TEMPLATE`. ## Limits to plan around Each line sends to 50 new contacts and 150 total messages per day, paced at up to 49 new contacts per hour ([rate limits](/features/rate-limits)). Trigger only on real opt-ins. Spam reports, not volume, are what get a line banned ([line health](/troubleshooting/line-health-and-restrictions)). Turn on Customer.io message throttling for the journey, and add lines to scale. # How to Send iMessage from GoHighLevel (GHL) Source: https://docs.tuco.ai/guides/send-imessage-from-gohighlevel Send iMessage from GoHighLevel with Tuco AI — trigger a blue-bubble text from any GHL workflow via webhook, or the Send via Tuco Marketplace action. **You send iMessage from GoHighLevel by connecting GHL to Tuco AI and calling Tuco's Send Message API from a GHL workflow — the fastest way is a plain Webhook action pointed at `https://app.tuco.ai/api/messages` with your Tuco API key.** GoHighLevel has no native iMessage channel, so Tuco provides the Apple-connected sending lines and handles the iMessage availability check plus SMS fallback automatically. You can also use the **Send via Tuco** GHL Marketplace action for contact-ID-only sends and native voice notes. ## Method 1 — Send from a GHL workflow with a Webhook (fastest) No Marketplace app or action secret required — just your Tuco API key. **1. Add a Webhook action** In your GHL workflow, add a **Webhook** action — Method `POST`, URL `https://app.tuco.ai/api/messages`. **2. Add your API key header** Header `Authorization` = `Bearer tuco_xxxxxxxxxxxxx` (your [Tuco API key](/api-reference/api-keys)). **3. Map only the message** Under **Custom Data**, set `message` (required). Optionally add `lineId` to pin a sending line and `attachmentUrls`. GHL already attaches the full contact payload, so Tuco reads `phone` → recipient, `contact_id` → GHL contact, `location.id` → location, `full_name` → name, and `user.email` → owner automatically. If the contact has no phone or email, the send fails with `missing_recipient`. Full field-by-field mapping and a copy-paste example live on the [Send Message reference](/api-reference/endpoint/send-message#send-straight-from-a-gohighlevel-webhook). ## Method 2 — The "Send via Tuco" Marketplace action Use the GHL Marketplace **Send via Tuco** action when you want Tuco to look up the recipient, pick a line, and run compliance checks from only a contact ID — or when you want to send a **native iMessage voice note** (the play-button bubble, not a file link). Find both setups in your Tuco dashboard under **Leads → AI & API**. ## Control the channel with a GHL tag Tuco reads a GHL **contact tag** live on every send, so you can force a channel instantly — no sync, no reinstall: | Tag on the contact | Effect | | - | - | | `forcefallback` | Skip the iMessage check and send via your configured SMS fallback (Twilio / GHL / custom webhook). Use for contacts you know aren't on iMessage. | | *(no tag)* | Normal flow — try iMessage first, fall back only if the contact isn't reachable on iMessage. | The tag is matched loosely, so `forcefallback`, `force-fallback`, and `Force Fallback` all work. `forcefallback` changes the channel only — a fallback must be configured under **Settings → When iMessage isn't available**. ## Connect GoHighLevel to Tuco **1. Enter your GHL credentials** In Tuco go to **Integrations → CRM**, enter your GHL **API key** and **Location ID**, and click **Test & Connect**. A full contact sync starts automatically and re-syncs every 15 minutes. **2. Grant the required scopes** Location access, Contacts (search/read), and Tags (read) are required. Users-read, Custom-fields-read, Contact-tags add/remove, and Conversations-create are recommended for owner mapping, field mapping, and activity logging. ## Frequently asked questions > [accordion] Does GoHighLevel send iMessage natively? > > No. GHL sends SMS and email but cannot send iMessage. Tuco AI adds the iMessage channel by sending from Apple-connected lines and exposing a Send Message API and a GHL Marketplace action. > [accordion] Do I need the Marketplace app to send an iMessage? > > No. The quickest method is a plain GHL Webhook action to the Send Message API using your Tuco API key. The Marketplace "Send via Tuco" action is optional and adds contact-ID lookups and native voice notes. > [accordion] How do I send an iMessage voice note from GHL? > > Use the Send via Tuco Marketplace action with a public audio URL, set `message` to `_attachment_only_`, and set `voiceNote` to `true`. Note that attachments (including voice notes) are blocked on the first-ever message to a contact — warm them up with a text first. > [accordion] Can I force a contact to SMS instead of iMessage? > > Yes. Add the `forcefallback` tag to the GHL contact. Tuco reads it live on every send and routes that contact through your SMS fallback. > [card] [GoHighLevel integration](/integrations/ghl) > > Full GHL setup: sync, tags, owner mapping, voice notes, and Check for Replies. # How to Send iMessage from HubSpot Source: https://docs.tuco.ai/guides/send-imessage-from-hubspot Send automated iMessage (blue-bubble) texts from HubSpot with Tuco AI: connect via OAuth, sync contacts, and send from Tuco or a HubSpot workflow webhook. **You send iMessage from HubSpot by connecting HubSpot to Tuco AI, which syncs your HubSpot contacts and then sends real iMessage (blue-bubble) texts on your behalf — with automatic SMS fallback for contacts who aren't on iMessage.** HubSpot has no native iMessage channel, so you need a bridge like Tuco. There are two ways to trigger the send: send from Tuco to your synced HubSpot contacts (no code), or fire a Tuco send from a HubSpot workflow with a webhook action. ## Why HubSpot can't send iMessage on its own HubSpot sends email and SMS (via integrations), but it cannot send iMessage — iMessage runs only through Apple's network from a signed-in Apple ID. Tuco AI provides Apple-connected sending "lines," so HubSpot becomes the system of record and Tuco becomes the iMessage sending layer. ## Method 1 — Connect HubSpot and send from Tuco (no code) Best for one-off and bulk outreach to synced contacts. **1. Connect HubSpot** In Tuco go to **Integrations → CRM → Connect with HubSpot** and authorize via OAuth (about 30 seconds). A full contact sync starts automatically; after that, Tuco pulls contacts modified in HubSpot every 15 minutes and deduplicates by phone number. **2. Check iMessage availability** Tuco automatically checks whether each synced contact can receive iMessage, so blue-bubble-eligible contacts are messaged over iMessage and the rest fall back to SMS. See [Check iMessage availability](/guides/check-imessage-availability). **3. Send your messages** [Send to your leads](/features/send-messages) with your message, personalization variables, and schedule. For follow-ups, use Method 2 so your HubSpot workflow decides when each one goes out. ## Method 2 — Trigger an iMessage from a HubSpot workflow Best for real-time, event-driven sends (e.g. "text me when a deal reaches Stage 2"). This uses HubSpot's **Send a webhook** workflow action, available on HubSpot Operations Hub / Professional tiers. On plans without the webhook action, use a Custom Code action or Method 1 instead. 1. In your HubSpot workflow, add a **Send a webhook** action — method `POST`, URL `https://app.tuco.ai/api/messages`. 2. Add header `Authorization: Bearer tuco_xxxxxxxxxxxxx` (your [Tuco API key](/api-reference/api-keys)). 3. Send a JSON body with the contact's `phone` (or `email`) and your `message`. Optionally pin a sending line with `lineId` or add `attachmentUrls`. Full field reference: [Send Message API](/api-reference/endpoint/send-message). Tuco runs the iMessage availability check and SMS fallback automatically, so you don't have to handle channel selection inside HubSpot. ## What syncs between HubSpot and Tuco | HubSpot field | Tuco field | | - | - | | firstname / lastname | First / Last name | | phone | Phone (used for iMessage) | | email | Email | | company / jobtitle | Company / Job title | | hubspot\_owner\_id | Owner (via mapping) | | any custom property | Tag or custom field | Owner mapping means messages are attributed to the right rep, and message activity can be logged back to the HubSpot contact timeline. See the full [HubSpot integration](/integrations/hubspot) reference. ## Frequently asked questions > [accordion] Does HubSpot have a native iMessage integration? > > No. HubSpot cannot send iMessage on its own. Tuco AI is the bridge — it connects to HubSpot via OAuth and sends real iMessage texts from Apple-connected lines, with SMS fallback. > [accordion] Do I need Operations Hub to send iMessage from a HubSpot workflow? > > Only for Method 2 (the webhook-triggered send), which relies on HubSpot's "Send a webhook" workflow action. Method 1 — syncing contacts and sending from Tuco — works on any HubSpot tier. > [accordion] What happens if a contact isn't on iMessage? > > Tuco checks iMessage availability before sending and automatically routes non-iMessage contacts to your configured SMS fallback, so the message still lands. See [failures and fallbacks](/features/failures-and-fallbacks). > [accordion] Can I use HubSpot deal stages or properties to control sends? > > Yes. HubSpot properties can be used as live advance or exit conditions in Goal Bots — each check queries the live HubSpot API. > [card] [Connect HubSpot](/integrations/hubspot) > > Full HubSpot setup: sync, owner mapping, property mapping, and Goal Bot conditions. # Atomic Duplicate Guard — POST /api/messages Source: https://docs.tuco.ai/imessage-double-send-guard How Tuco prevents duplicate sends from concurrent API calls or upstream retries. Fires at /api/messages for every channel (iMessage, SMS, email). > **Status:** Shipped 2026-05-17 on `dev`, on `master` once verified. Replaces the previous 2-min find-then-insert guard which had a TOCTOU race that allowed concurrent dupes through. ## TL;DR * Every `POST /api/messages` claims an **atomic lock** on `(workspaceId, recipientPhone, recipientEmail, exact body text)` before sending. * If a second identical POST arrives within **15 minutes**, it gets the original message back with `duplicateOnly: true` and **no new send fires**. * Works WITHOUT an `Idempotency-Key` header — automatic, server-side, no caller change required. * Idempotency-Key is still preferred when your client controls retries (24-hour window, exact-request match), but this guard exists for callers that don't set one. ## Why this exists Real-world incident, 2026-05-15 → 2026-05-17 (Frank Sondors' Mailforge integration → Tuco workspace `org_3C059wfibDQCpSfA0rbXVFsoJUk`): | Failure mode | Count in 7 days | Cause | | - | - | - | | Concurrent identical POSTs \~90-350 ms apart | 9 of 12 | Mailforge fired the same request twice; old guard's `findOne` returned null for both before either inserted, so both proceeded. | | Identical POST retried 2-15 min later | 3 of 12 | Upstream retry-with-backoff. Old 2-min window expired before the retry. | | Identical POST replayed 14 h later | 1 of 12 | Outside any reasonable window — needs `Idempotency-Key`. | The fix closes the first two failure modes for **every caller** without requiring them to send `Idempotency-Key`. ## What gets blocked vs. allowed **Blocked:** two POSTs with **byte-identical** `(workspaceId, recipientPhone, recipientEmail, message body)` within 15 minutes. **Allowed (NOT blocked):** | Scenario | Why it's allowed | | - | - | | Bulk send to 100 leads using the same template | Each lead has a different `recipientPhone`/`recipientEmail` → 100 distinct hashes | | Same recipient, body differs by one character | Different hash | | Same recipient + same body, **>15 min apart** | First lock expired via TTL | | Same recipient + same body, **different workspace** | Different `workspaceId` → different hash | | Same body to two different leads who happen to share a phone | Same hash, **blocked** (this is the right call — one human, one phone) | | Failed-validation requests (404 lead, 400 attachments, etc.) | Guard runs AFTER validation, so failed requests never hold a lock | ## How it works under the hood 1. POST arrives, passes auth + validation. 2. Tuco computes `hash = sha256(workspaceId + recipientPhone + recipientEmail + body)`. 3. Tuco attempts `insertOne` into the internal dedup-lock store with `_id = hash` and `expiresAt = now + 15 min`. 4. Mongo's built-in unique `_id` index decides the race: * **Insert succeeds** → caller owns the slot. Proceeds with the send. The resulting message ID is attached to the lock so future retries get the right sibling back. Lock is auto-released if the send hard-fails before the message doc lands. * **Insert fails with E11000** → another request beat us. We look up the sibling message in `messages` (workspace + recipient + body, last 15 min) and return it with `duplicateOnly: true`. If the sibling hasn't been written yet (the original is still in flight), we poll for up to 3 s, then return `duplicateOnly: true, message: null` rather than risk a duplicate send. * **Insert fails with any other error** → guard logs the error and falls through. The request proceeds without dedup protection. The guard is built to never break the send path. 5. A TTL index on `expiresAt` (with `expireAfterSeconds: 0`) clears the lock 15 minutes after acquisition. Mongo's TTL monitor sweeps every \~60 s, so worst-case lock lifetime is \~16 min. ## Response shapes ### Normal send ```json theme={null} { "success": true, "status": "sent", "message": { /* full message doc */ }, "leadId": "...", "ghlContactId": "...", "ghlLocationId": "...", "hsContactId": null, "hsPortalId": null } ``` HTTP **201** (or **200** when an existing lead was reused). ### Duplicate caught — sibling found ```json theme={null} { "success": true, "duplicateOnly": true, "duplicateMessage": "Same message text already sent to this contact 42s ago — returning existing message instead of sending again", "message": { /* the original sibling message doc */ }, "leadId": "...", "ghlContactId": "...", "ghlLocationId": "...", "hsContactId": null, "hsPortalId": null } ``` HTTP **200**. **No new send fires.** `message._id` is the original sibling — your CRM workflow can branch on `duplicateOnly === true` and treat it as a no-op success. ### Duplicate caught — original still in flight ```json theme={null} { "success": true, "duplicateOnly": true, "duplicateMessage": "A previous identical request is still being processed — refusing to send again. Retry once the original completes.", "message": null, "leadId": null, "ghlContactId": null, "ghlLocationId": null, "hsContactId": null, "hsPortalId": null } ``` HTTP **200**. The guard saw an active sibling lock but the original's message doc hadn't landed within the 3-s poll window. Safer to refuse than risk a duplicate — when the original finishes, a fresh retry from your side will receive the standard "duplicate caught — sibling found" response. ## Known sharp edges * **Failed sends still return the failed sibling on retry within 15 min.** If your first send ended in `status: "failed"` and you immediately retry with the same body, you'll get the failed sibling back with `duplicateOnly: true`. To force a fresh send: change the body, wait 15 min for the lock to TTL, or manually delete the lock (`db.collection('the internal dedup-lock store').deleteOne({ _id: '' })`). * **Polling cost.** A duplicate request that arrives before the original's message doc lands holds the connection for up to 3 s. Real-world: `createMessage` inserts the message doc within \~50 ms of acquiring the lock, so most polls resolve on the first iteration. * **Lock leak on process crash.** Mitigated by the TTL — locks always expire 15 min after acquisition regardless of process state. ## How it interacts with `Idempotency-Key` The `Idempotency-Key` header check at `/api/messages` runs **before** this guard. If your client sends an `Idempotency-Key`, retries of the same request return the original response from the internal idempotency-key store (24-hour window) without ever reaching the dedup guard. | You set `Idempotency-Key`? | Behavior | | - | - | | **Yes**, same key on retry | Original response replayed from the internal idempotency-key store — exact-request semantics, 24 h window | | **Yes**, different key | Treated as new request; dedup guard then catches body-level duplicates within 15 min | | **No** | Dedup guard is the only protection. 15 min window on `(workspace, recipient, body)` | `Idempotency-Key` is preferred when you control the caller. The dedup guard is the safety net for everyone else. ## What's NOT changing * `(workspaceId, contactIdentifiers)` unique index on `leads`. One phone = one lead per workspace. * One conversation thread per `(workspaceId, recipientPhone)`. * `Idempotency-Key` semantics on `/api/messages` (still 24 h, still preferred when callers can set it). * HubSpot/GHL workflow plugin behavior — the guard fires identically for every caller because it sits on the shared `/api/messages` endpoint. ## See also * [`api-reference/endpoint/send-message`](/api-reference/endpoint/send-message) — endpoint reference * [`features/send-messages`](/features/send-messages) — feature overview * Source: `src/lib/dedupGuard.ts`, `src/app/api/messages/route.ts` (tuco-app) # Welcome to Tuco AI Source: https://docs.tuco.ai/index Tuco AI docs: iMessage automation for B2B sales teams. Verify Apple ID availability, send personalized 1:1 messages, and automate replies. ## Getting Started Tuco AI helps you contact leads using iMessage Automation, verify iMessage availability, and send personalized 1:1 messages triggered from your CRM. Get up and running in minutes. > [card] [Quick Start Guide](/quickstart) > > Set up your account and send your first message in under 5 minutes > [card] [Upload Your Leads](/features/upload-leads) > > Import leads from CSV, Google Sheets, HubSpot, or Salesforce *** ## Core Features Everything you need to manage leads and communicate effectively. > [card] [Upload Leads](/features/upload-leads) > > Import leads from multiple sources with automatic validation and deduplication > [card] [Check Availability](/features/check-availability) > > Verify iMessage support before sending to maximize delivery rates > [card] [Send Messages](/features/send-messages) > > Send iMessage, SMS, or email with immediate or scheduled delivery *** ## Popular Guides Step-by-step answers to the most common iMessage automation questions. > [card] [Automate iMessage for Sales](/guides/automate-imessage-sales-outreach) > > Verify availability, trigger personalized sends, auto-reply, and fall back to SMS. > [card] [Send iMessage from HubSpot](/guides/send-imessage-from-hubspot) > > Connect HubSpot and send blue-bubble texts from a HubSpot workflow. > [card] [Send iMessage from GoHighLevel](/guides/send-imessage-from-gohighlevel) > > Trigger an iMessage from any GHL workflow with a webhook. > [card] [Send iMessage from Close](/integrations/close) > > Start a sequence from a Close lead field and reply from the lead page. > [card] [Check iMessage Availability](/guides/check-imessage-availability) > > Tell whether a number can receive iMessage before you text it. > [card] [Bulk iMessage (Safely)](/guides/send-bulk-imessage) > > Why iMessage should be triggered, not blasted. > [card] [iMessage vs SMS for Sales](/guides/imessage-vs-sms-for-sales) > > When to use each channel — and how to use both automatically. > [card] [Best iMessage Automation Tools](/guides/best-imessage-automation-tools) > > How the iMessage automation tools compare in 2026. > [card] [Is iMessage Marketing Legal?](/guides/imessage-compliance-tcpa) > > TCPA, consent, and opt-out rules for compliant outreach. *** ## Why Tuco AI? > [accordion] 🎯 Maximize Deliverability > > Automatically check iMessage availability and route messages through the optimal channel for each recipient > [accordion] ⚡ Scale Your Outreach > > Trigger personalized 1:1 messages from CRM events, within per-line rate limits — never spam blasts > [accordion] 🔗 Seamless Integrations > > Connect with your existing tools: HubSpot, GoHighLevel, Close, Google Sheets, and more > [accordion] 📊 Track Everything > > Monitor delivery status and engagement metrics in real-time *** ## Popular Workflows > [card] Quick Message > > **Perfect for:** Testing, one-off messages, or reaching contacts not in your system > > 1. Click Quick Send > 2. Enter recipient (phone or email) > 3. Compose message > 4. Send immediately or schedule for later > [card] Bulk Send > > **Perfect for:** Personalized outreach to a list of leads > > 1. Upload or select leads > 2. Check iMessage availability > 3. Compose personalized message > 4. Schedule for optimal timing *** ## Developer Resources Build custom integrations and automate your workflows with our REST API. > [card] [API Documentation](/api-reference/introduction) > > Complete API reference with authentication, endpoints, and examples > [card] [Webhooks](/api-reference/endpoint/webhook) > > Receive real-time notifications for message delivery and status updates *** ## Support & Community > [card] [Documentation](/quickstart) > > Comprehensive guides and tutorials > [card] [Email Support](mailto:support@tuco.ai) > > Get help from our team # Close CRM Integration Source: https://docs.tuco.ai/integrations/close Connect Close to Tuco AI: move a lead into a status and it gets texted, see every message in Close's conversation view, and reply or call from the lead page. ## What You Get * **Move a lead, it gets texted** — map a status to a message once; after that, changing a lead's status sends it * **Native conversation view** — every message appears in Close's own SMS thread, not buried in notes * **Reply notifications** — inbound replies raise a Close Inbox notification, the way Close already tells you about messages * **Text and call from the lead page** — a panel and a click-to-call button, right where you work * **Contact sync** — Close contacts become Tuco leads, deduplicated by phone * **Owner mapping** — map Close users to Tuco team members so messages come from the right rep > [!NOTE] > > Only one CRM can be connected at a time. Disconnect HubSpot, GoHighLevel or Pipedrive before connecting Close. ## Connecting Close 1. Go to **Integrations → CRM** 2. Click **Connect with Close** 3. Authorize via OAuth (takes 30 seconds) 4. Tuco sets up your Close account automatically — see [What Tuco adds to your Close account](#what-tuco-adds-to-your-close-account) ## Sending your first texts Setup lives in Tuco, in one table. Pick a status, pick a number, write the text: | When status becomes | Text them from | Message | | - | - | - | | Interested | +1 555 867 5309 | `Hey {first}, saw you're interested — want me to send a quote?` | | Qualified | +1 555 867 5309 | `{first}, got 10 min this week to walk through it?` | | Customer | +1 555 867 5309 | `Welcome aboard {first}! I'll be your main contact — text me any time.` | That's it. Move a lead into one of those statuses and Tuco texts them. ### Variables you can use | Variable | Becomes | | - | - | | `{first}` | The contact's first name | | `{name}` | Their full name | | `{company}` | The Close lead name | | `{status}` | The lead's current status | | *Any lead field* | Whatever you named it in Close — `{Budget}`, `{Renewal Date}` | Your own Close lead custom fields work by name, exactly as you named them, and capitalisation and spacing don't matter. The setup table lists everything your account has, and warns you if you type a name that isn't one of them. If we don't know a contact's name, `{first}` and `{name}` become "there" — never a raw `{first}` at a real person. A field the lead hasn't got renders as nothing at all, so write the sentence so it still reads without it. If a message ends up completely empty, we don't send it. ### Four ways a lead lands in a status All of them work, because all of them are the same change as far as Tuco is concerned: * **A rep drags the lead** on the Leads board, or changes the status on the lead page * **In bulk from a Smart View** — select a segment, change the status, the whole segment gets texted * **A Close Workflow** with an **Update Lead** step that sets the status * **Anything else** that sets a status — a form, an API call, another integration > [!NOTE] > > You don't have to build a Workflow at all. If your team already moves leads through statuses, you're done after filling in the table. ### Using a Close Workflow If you do want it automated: 1. **Workflows → New Workflow → Start from scratch** 2. Pick a trigger — Lead event, Form Submission, Call event, whatever starts it 3. **Add Step → Update Lead** 4. **Add Field → Lead Status →** the status you mapped in Tuco > [!WARNING] > > Leave **Overwrite existing values** ON only if the workflow runs once per lead. If it can run repeatedly, turn it off — otherwise every run rewrites the status, and re-entering a status is a fresh trigger. ### Won't it text people twice? No. The same message to the same lead is ignored for 7 days, so a rep bouncing a lead Interested → Qualified → Interested doesn't send twice. A **different** status means a different message, so that does send — which is what you want. ### Why a status and not a "send text" step Close Workflows have nine step types — Email, Call, SMS, Assign User, Task, Create Opportunity, Update Lead, Update Opportunity and Filter — and **none of them can call an outside service**. So no texting app can be a step inside Close's workflow builder. Every one of them, Tuco included, watches for a change on the lead instead. We watch the status because your Close account already has statuses, so there's nothing to create before you start. > [!WARNING] > > Don't use Close's built-in **SMS** step for Tuco messages. That sends through Close's own carrier from a different number — your lead gets a green bubble from a stranger, and you pay twice. ### What this does and doesn't give you | | | | - | - | | ✅ Any Close trigger can start a text | Statuses, workflows, forms, bulk edits, the API | | ✅ No Zapier, Make or middleware | Update Lead is a native Close step | | ✅ Every message and reply lands on the lead | As a native SMS activity, in Close's own conversation view | | ✅ Replies ping your Close Inbox | Same as a Close-native text | | ❌ Tuco isn't a step *inside* the workflow | Close can't wait for the reply before its next step — no app can; there's no step type for it | | ❌ Close's workflow goals don't see the reply | The workflow sets the status and moves on; the conversation continues in Close's timeline | ## Sending from Your Own System If you'd rather drive sends yourself than use status mapping, call the [send API](/api-reference/messages) and pass the Close IDs alongside the message. Tuco logs it to the right Close lead, and any reply comes back to the same place. ```bash theme={null} curl -X POST https://app.tuco.ai/api/messages \ -H "Authorization: Bearer $TUCO_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "message": "Hey Jane — following up on your demo request.", "messageType": "imessage", "recipientPhone": "+15558675309", "closeOrgId": "orga_...", "closeLeadId": "lead_...", "closeContactId": "cont_..." }' ``` | Field | Required | Notes | | - | - | - | | `message` | yes | The text to send | | `recipientPhone` | yes | E.164. Read it off the Close contact | | `closeLeadId` | for logging | Where the activity lands in Close | | `closeContactId` | recommended | Pins which person on the lead | | `closeOrgId` | recommended | Only strictly needed if you run more than one Close org | | `fromLineId` | no | Omit and Tuco picks a line for you | > [!NOTE] > > Pass at least `closeLeadId`. Without it the message still sends, but Tuco has no record to attach it to — it won't appear on the Close timeline, and a reply can only be matched back by phone number. **Replies need nothing extra.** Tuco stores the Close IDs on the message, so when the lead replies, the reply is logged to the same Close lead and raises a Close Inbox notification — no second API call, no webhook to build on your side. > [!NOTE] > > You don't need a status trigger at all if you're sending this way. Use whichever fits: statuses to let Close drive, the API to keep control of timing yourself. Both log to Close identically. ## Messages in Close Every message — outbound and inbound — is written to Close as an **SMS activity** on the lead, so it appears in Close's normal conversation view and counts in Close's reporting. Inbound replies also raise a **Close Inbox notification**, so your reps get told about a reply the same way they're told about everything else. > [!NOTE] > > Tuco only ever *logs* these messages. It never asks Close to send anything, so a lead is never texted twice. ### If your plan doesn't include SMS On Close plans without SMS, Tuco logs each message as a **Note** on the lead instead. Nothing is lost — the thread just reads as notes rather than as a conversation. The Close card tells you when this is happening, so it's never a silent downgrade. ## Replying and Calling Close doesn't allow third-party apps to send through its own message composer, so replies go through Tuco. There are two ways in, and both live on the Close lead page: **The Tuco browser extension** (recommended) adds **Text with Tuco** and **Call** buttons to every lead. Texting opens the conversation in a small window; calling connects through your verified line. **Lead-page links** — Tuco also adds "Text with Tuco" and "Call with Tuco" to the three-dot menu next to the lead name, so the integration works without installing anything. > [!WARNING] > > Replying in Close's own SMS box sends through Close's phone number, not your Tuco line — so the lead gets a text from a different number and it won't appear in your Tuco conversation. Always reply from the Tuco panel. ## Contact Sync ### How it works * **First sync** — imports your Close contacts into a "Close Import" list * **Incremental sync** — every 15 minutes, picks up contacts changed since the last sync * **Deduplication** — contacts are matched by phone; an existing lead is updated, never duplicated * **Manual sync** — **Sync now** for recent changes, **Full sync** to re-import from scratch ### What syncs | Close field | Tuco field | | - | - | | Contact name | First / Last name | | Contact phone (mobile preferred) | Phone | | Contact email | Email | | Contact title | Job Title | | Lead display name | Company | | Contact owner | Owner (via mapping) | > [!NOTE] > > A Close **Lead** is the company; its **Contacts** are the people. Tuco creates one lead per Close *contact*, since that's who holds the phone number, and records the Close lead's name as the company. ### Accounts over 10,000 contacts Close limits how far an app can page through contacts in one pass — about **10,000**. Larger accounts still import completely: each sync picks up where the last one stopped, so the import continues on the 15-minute schedule until it's done. A 200,000-contact account takes roughly five hours and needs nothing from you. The Close card says when an import is still partial. The one case that needs us is more than 10,000 contacts created in Close on a single day — usually a bulk import. Email [support@tuco.ai](mailto:support@tuco.ai) and we'll run it for you. ## Owner Mapping Map Close users to Tuco team members so each rep's leads send from that rep's line. 1. Go to **Integrations → CRM** 2. Under **Close users → Tuco reps**, pick a Tuco member for each Close user 3. Click **Save mapping** Unmapped users fall back to your workspace's default line. ## What Tuco Adds to Your Close Account Connecting Close creates three things. Disconnecting removes them. | Item | Purpose | | - | - | | **Tuco Status** lead field | Where Tuco writes back what happened | | A webhook subscription | How Tuco hears about a lead's status changing | | Two lead-page links | "Text with Tuco" and "Call with Tuco" | > [!NOTE] > > Creating lead-page links requires a Close **admin**. If whoever connects Close isn't an admin, everything else still works — you'll use the browser extension for texting and calling instead. ## Disconnecting Go to **Integrations → CRM → Disconnect** on the Close card. Tuco removes its webhook and lead-page links from your Close account and revokes its access. Your messages stay on the Close timeline — they're ordinary Close activities and are yours to keep. ## Troubleshooting > [accordion] A lead isn't sending > > Check the **Tuco Status** field on the lead — it usually says why. The common causes are a status that isn't mapped in Tuco, and no contact on the lead having a phone number. > > Also check the Close card under **Integrations → CRM**. It shows the live state of the connection and says which part isn't working — a missing webhook subscription, a connection that needs re-authorising, or a contact import that hasn't run. > > If a lead that's been messaged before isn't sending again, check the 7-day window — the same message to the same lead is suppressed for 7 days. A different status sends a different message and isn't affected. > [accordion] Messages aren't appearing in Close > > Open the Close card under **Integrations → CRM**. If it shows *"Messaging isn't wired up yet"*, click **Reconnect**. If that doesn't clear it, contact [support@tuco.ai](mailto:support@tuco.ai). > [accordion] A lead got a text from an unfamiliar number > > That's Close's own SMS, not Tuco — someone replied in Close's message box instead of the Tuco panel. Replies have to go through **Text with Tuco** to send from your Tuco line. > [accordion] Status texts stopped sending > > Close pauses a webhook subscription after three days of failed delivery. Tuco checks for this every few hours and reconnects automatically, so this usually resolves on its own. If it's been longer than that, click **Reconnect** on the Close card. > [accordion] Not all my contacts imported > > See [Accounts over 10,000 contacts](#accounts-over-10-000-contacts). # Email Bridge Setup Source: https://docs.tuco.ai/integrations/email-bridge Set up the Tuco Email Bridge: email +phone@send.tuco.ai from Gmail, Outlook or any client and Tuco sends it as an iMessage, then confirms by email. Send iMessages to any phone number by composing an email. Works from Gmail, Outlook, or any email client. ## How It Works 1. Compose an email in your email client 2. Set **To** to: `+19045551234@send.tuco.ai` 3. Write your message in the email body 4. Hit **Send** 5. Tuco sends it as an iMessage and emails you a confirmation ## Email Format ### Basic (uses first available line) ``` To: +19045551234@send.tuco.ai Subject: (anything — ignored) Body: Hey, wanted to follow up on our conversation yesterday. ``` ### Specific line ``` To: +19045551234-line_abc123@send.tuco.ai ``` Find your line ID on the **Lines** page in the dashboard. ## Requirements * Your email address (From) must be registered in Tuco * Your workspace must have at least one active iMessage line * Phone number must be in E.164 format (`+` country code + number) ## Error Handling If something goes wrong, you receive a bounce email: | Error | Cause | | - | - | | Invalid phone number | Check format: `+19045551234` | | Not authorized | Your email isn't registered in Tuco | | No active lines | Set up a line at Lines → Purchase | | Send failed | Recipient may not have iMessage | ## Security > [!WARNING] > > The Email Bridge verifies your identity by looking up your sender email in Tuco's user database. SPF/DKIM from your email provider is a secondary check — not the primary auth mechanism. Unauthorized emails receive a bounce explaining they need to register at app.tuco.ai first. # GoHighLevel iMessage Integration Source: https://docs.tuco.ai/integrations/ghl Connect GoHighLevel to Tuco AI to send iMessage from any GHL workflow, sync contacts and tags, and run follow-ups from GHL workflows. **Tuco AI is the native GoHighLevel iMessage integration: connect GHL with your API key and Location ID, and Tuco syncs your contacts, reads your tags live, and sends real iMessage (blue-bubble) texts from any GHL workflow — with automatic SMS fallback.** GoHighLevel has no native iMessage channel, so Tuco adds it and keeps GHL as your system of record. > [!TIP] > > Just want to fire an iMessage from a workflow? See the step-by-step [Send iMessage from GoHighLevel](/guides/send-imessage-from-gohighlevel) guide. ## What You Get * **Contact sync** — Import GHL contacts into Tuco with deduplication * **Owner mapping** — Map GHL users to Tuco team members * **Tag sync** — GHL contact tags imported automatically * **Custom field sync** — Map GHL custom fields to Tuco custom fields or tags ## Connecting GoHighLevel 1. Go to **Integrations → CRM** 2. Enter your GHL **API key** and **Location ID** 3. Click **Test & Connect** 4. A full sync starts automatically > [!NOTE] > > Only one CRM can be connected at a time. Disconnect HubSpot before connecting GHL. ### Required API scopes * Location access * Contacts: search and read * Tags: read location tags ### Recommended scopes * Users: read (for owner mapping) * Custom fields: read (for field mapping) * Contact tags: add/remove (for goal bot tags) * Conversations: create (for activity logging) ## Contact Sync ### How it works * **First sync** — imports all GHL contacts into a "GHL Import" list * **Incremental sync** — every 15 minutes, syncs recently modified contacts * **Deduplication** — matched by phone number * **Tags** — GHL contact tags are imported into Tuco's tag system ### What syncs | GHL Field | Tuco Field | | - | - | | firstName | First Name | | lastName | Last Name | | email | Email | | phone | Phone | | companyName | Company | | tags | Tags | | assignedTo | Owner (via mapping) | ## Owner Mapping Same as HubSpot — map GHL users to Tuco members. 1. **Integrations → CRM → Owner Mapping** 2. Map each GHL user to a Tuco member 3. **Save & Re-sync** ## Custom Field Mapping Map GHL custom fields to Tuco tags or custom fields. 1. **Integrations → CRM → Property Mapping** 2. Select a GHL custom field 3. Choose Tag or Custom Field target 4. **Save & Re-sync** ## Channel control with tags Use a GHL **contact tag** to control which channel a lead's outbound messages go out on. Tags are read live on every send (workflow action **and** conversation-provider / CloseBot), so they take effect immediately — no sync, no custom field, no reinstall. | Tag on the contact | Effect | | - | - | | `forcefallback` | **Skip the iMessage check** and send via the workspace's configured fallback (SMS — Twilio / GHL / custom webhook). Use it for leads you already know aren't on iMessage, or that you simply want on SMS. | | *(no tag)* | **Normal flow** — try iMessage first, fall back only if the contact isn't reachable on iMessage. | The tag name is matched loosely (case-insensitive, ignoring spaces/dashes/underscores), so `forcefallback`, `force-fallback`, `force_fallback`, and `Force Fallback` all work. > [!NOTE] > > `forcefallback` only changes the **channel**, not delivery. The lead must have a fallback > configured (**Settings → When iMessage isn't available**). With no fallback set up the > send returns an error instead of silently delivering over iMessage. Add or remove the tag > any time to flip a lead between iMessage-first and SMS-only. ## Send iMessages from a GHL workflow The simplest way to trigger a Tuco iMessage from a GHL workflow is a plain **Webhook** action pointed at the Send Message API — no Marketplace app or action secret, just your Tuco API key. GHL's Webhook action already attaches the full contact payload, so **the only thing you map is the message**. 1. In your workflow, add a **Webhook** action — Method `POST`, URL `https://app.tuco.ai/api/messages`. 2. Add a header: `Authorization` = `Bearer tuco_xxxxxxxxxxxxx` (your [API key](/api-reference/api-keys)). 3. Under **Custom Data**, set `message` (required). Optionally add `lineId` (pin a sending line) and `attachmentUrls`. Tuco reads GHL's native contact fields to fill in the recipient and contact link automatically (`phone` → recipient, `contact_id` → GHL contact, `location.id` → GHL location, `full_name` → name, `user.email` → owner). You don't map any of those. > [!NOTE] > > Full field-by-field mapping and a copy-paste example are on the > [Send Message → "Send straight from a GoHighLevel webhook"](/api-reference/endpoint/send-message#send-straight-from-a-gohighlevel-webhook) > reference. If the contact has no phone or email the send fails with `missing_recipient`. > [!TIP] > > Want Tuco to look up the recipient, pick a line, and run compliance checks for you from > only a contact ID? Use the GHL Marketplace **Send via Tuco** action instead — see your > in-app **Leads → AI & API** tab for both setups. ## Send a voice note from GHL The Marketplace **Send via Tuco** (Send iMessage) action can deliver a native iMessage **voice note** — the recognizable play-button bubble, not a file link. You supply a clean audio URL and flip one toggle; Tuco transcodes the audio to the voice-note format for you. ### Get an audio URL You need a public `https://…` link to an audio file (`mp3`, `m4a`, `wav`, `aac`, `ogg`, or `caf`), **≤ 5 minutes** long. If you upload it to Tuco (the easiest route, below) the file must also be **≤ 5 MB** — which five minutes of speech comfortably fits under. The easiest way to get one: * In the dashboard, open **/uploads** (or the **Upload audio etc** tab on the **Leads** page), drag in your clip, and hit **Copy** to copy the link. * Or upload it programmatically with [`POST /api/attachments/upload`](/api-reference/upload-attachment). Either way the URL belongs to your workspace, so it passes Tuco's attachment ownership guard automatically. ### Configure the action fields In your GHL workflow, add the **Send via Tuco** action and set these fields: | Field | Required | Value | | - | - | - | | `contactId` | **Yes** | The contact to send to (map from the trigger contact). | | `message` | **Yes** | Set the **Default value** to `_attachment_only_` — a magic word that sends the audio with **no caption**. GHL requires this field to be non-empty; leaving it truly blank errors with `Missing message`. | | `attachmentUrl` | **Yes** | A clean `https://…` audio URL (see above). Must be `mp3`/`m4a`/`wav`/`aac`/`ogg`/`caf` and ≤ 5 min. Files uploaded to Tuco are capped at 5 MB. | | `voiceNote` | **Yes (for a voice note)** | Set the **Default value** to `true`. Without it the audio sends as a **plain file**, not a native voice memo. | | `skipIfReplied` | Optional | Leave blank, or `true`, or a window like `7d` / `1mo` to skip the send when the contact has already replied. See [`skipIfReplied`](/api-reference/endpoint/send-message#skip-if-the-contact-already-replied). | > [!WARNING] > > A voice note — like any attachment — is **blocked on the first-ever message** to a > contact. It only lands on a contact you already have a conversation with. Warm the > contact up with a plain text message first; the voice note lands on any later step. > [!NOTE] > > `_attachment_only_` needs a real `attachmentUrl` to go with it. If you set the magic > word but leave the URL empty, the action returns > `Used _attachment_only_ but no Attachment URL was provided`. To send audio **with** a > caption, put your caption in `message` instead of the magic word. > [!TIP] > > Want the audio to send as a **file** rather than a voice note? Leave `voiceNote` off > (or `false`). Everything else stays the same. ## Check for Replies (Marketplace workflow action) The **Check for Replies** action tells your workflow whether a contact has replied on iMessage since your last outbound message — and hands the recent conversation to later steps, so If/Else branches, AI steps, and webhooks can act on what was actually said. The action takes an optional `phone` field; leave it blank to use the contact's phone automatically. ### Response ```json theme={null} { "hasReplied": true, "hasEverReplied": true, "lastReply": "yes, tomorrow at 2 works!", "pastConversation": [ { "from": "+13025550123", "to": "+19045551234", "text": "hi — still interested?", "attachmentUrls": [], "direction": "sent", "fromLineId": "664f1c7fec719ac5207d6e9c", "status": "delivered", "at": "2026-07-14T10:00:00.000Z" }, { "from": "+19045551234", "to": "+13025550123", "text": "yes, tomorrow at 2 works!", "attachmentUrls": [], "direction": "received", "fromLineId": "664f1c7fec719ac5207d6e9c", "status": "delivered", "at": "2026-07-14T10:05:00.000Z" } ] } ``` | Field | Type | Description | | - | - | - | | `hasReplied` | boolean | `true` when the contact's newest inbound message is newer than your last outbound to them (or when they've messaged you and you never sent anything). | | `hasEverReplied` | boolean | `true` when the contact has ever replied, no matter what you've sent since. Stays `true` after follow-ups and auto-replies that would flip `hasReplied` back to `false`. | | `lastReply` | string | Full text of the contact's most recent reply. Empty string when they've never replied. | | `pastConversation` | array | The last 10 messages exchanged with the contact, both directions, oldest → newest. Empty when there's no conversation on record. | Each `pastConversation` item: | Field | Type | Description | | - | - | - | | `from` / `to` | string | Sender and recipient. For `direction: "sent"` that's your Tuco line → the contact; for `"received"` it's the contact → your line. | | `text` | string | Message body (empty for attachment-only messages). | | `attachmentUrls` | string\[] | URLs of any attachments on the message. | | `direction` | string | `"sent"` (you → contact) or `"received"` (contact → you). | | `fromLineId` | string | The Tuco line the exchange happened on. | | `status` | string | Message status (`sent`, `delivered`, `failed`, …) — failed sends are included, so check `status` if delivery matters. | | `at` | string | ISO 8601 timestamp. | > [!NOTE] > > `hasReplied` and `hasEverReplied` answer different questions. `hasReplied` means > "replied *since your last outbound*" — after you (or Tuco's AI copilot) send a > follow-up, it flips back to `false`. `hasEverReplied` never flips back: once the > contact has replied, it stays `true`. If your workspace has an auto-responder, > branch on `hasEverReplied` — the auto-reply usually lands within seconds, so > `hasReplied` will already be `false` by the time your workflow checks. Use > `hasReplied` only for strict wait-for-reply flows, and `lastReply` / > `pastConversation` for AI context. > If a line was later deleted, `from`/`to` may be empty for its messages — `fromLineId` > still identifies the line. ## Using GHL Data in Goal Bots GHL tags decide which leads a [goal bot](/features/goal-bots) answers: `includeTags` fires it, `excludeTags` vetoes it, and `onDoneTag` is written back when it books. A goal bot can also read your GHL calendar and book a real appointment. Every check calls the live GHL API, not cached data. # HubSpot Integration Source: https://docs.tuco.ai/integrations/hubspot Connect HubSpot to Tuco AI to sync contacts, map owners, and send iMessage — with live HubSpot properties driving Goal Bot conditions. ## What You Get * **Contact sync** — Import HubSpot contacts into Tuco with automatic deduplication * **Owner mapping** — Map HubSpot contact owners to Tuco team members * **Property mapping** — Sync custom HubSpot properties as tags or custom fields * **Activity logging** — Log Tuco messages to HubSpot contact timelines * **Goal Bot conditions** — Use live HubSpot properties as Goal Bot advance or exit conditions ## Connecting HubSpot 1. Go to **Integrations → CRM** 2. Click **Connect with HubSpot** 3. Authorize via OAuth (takes 30 seconds) 4. A full sync starts automatically > [!NOTE] > > Only one CRM can be connected at a time. Disconnect GoHighLevel before connecting HubSpot. ## Contact Sync ### How it works * **First sync** — imports all HubSpot contacts into a "HubSpot Import" list * **Incremental sync** — every 15 minutes, syncs contacts modified since last sync * **Deduplication** — contacts are matched by phone number; duplicates are merged, not created twice * **Force re-sync** — click "Full Re-sync" to re-import everything from scratch ### What syncs | HubSpot Field | Tuco Field | | - | - | | firstname | First Name | | lastname | Last Name | | email | Email | | phone | Phone | | company | Company | | jobtitle | Job Title | | hubspot\_owner\_id | Owner (via mapping) | ## Owner Mapping Map HubSpot contact owners to Tuco team members so messages come from the right person. 1. Go to **Integrations → CRM → Owner Mapping** 2. For each HubSpot owner, select the matching Tuco team member 3. Click **Save & Re-sync** ### How owner resolution works When syncing a contact, Tuco resolves the owner in this order: 1. **Manual mapping** — if you mapped this HubSpot owner to a Tuco member 2. **Email match** — if the HubSpot owner's email matches a Tuco member's email 3. **Fallback** — assigns to the earliest workspace member Each lead shows how its owner was assigned (Mapped / Auto-matched / Fallback) in the lead detail page. ### When a new member joins When a new team member joins your workspace, Tuco automatically reassigns leads where the HubSpot owner email matches the new member's email. No manual re-sync needed. ## Property Mapping Sync any HubSpot contact property as a **tag** or **custom field** in Tuco. 1. Go to **Integrations → CRM → Property Mapping** 2. Select a HubSpot property (e.g. `lifecyclestage`, `industry`) 3. Choose target: **Tag** or **Custom Field** 4. Optionally add a prefix (e.g. prefix "stage" → tag "stage:lead") 5. Click **Save & Re-sync** Custom fields synced from HubSpot are: * Visible in lead detail and sidebar * Usable as message variables ## Using HubSpot Data in Goal Bots HubSpot properties can be used as advance or exit conditions in [Goal Bots](/features/goal-bots). When a Goal Bot checks a HubSpot property, it calls the live HubSpot API — not stale cached data. # MCP Server Setup Source: https://docs.tuco.ai/integrations/mcp-server Set up the Tuco MCP server to manage your iMessage workspace from Claude Desktop, Cursor or any MCP-compatible AI agent in natural language. The Tuco MCP (Model Context Protocol) Server lets AI assistants manage your iMessage platform using natural language. ## Install ```bash theme={null} npx tuco-mcp ``` ## Configure Claude Desktop Add this to your Claude Desktop config file (`~/Library/Application Support/Claude/claude_desktop_config.json`): ```json theme={null} { "mcpServers": { "tuco": { "command": "npx", "args": ["tuco-mcp"], "env": { "TUCO_API_KEY": "tuco_your_api_key" } } } } ``` > [!NOTE] > > Get your API key from the **API Keys** tab in the [Tuco dashboard](https://app.tuco.ai/api-keys). ## Configuration The server is configured entirely through environment variables (or the matching CLI flags): | Variable | Required | Default | Description | | - | - | - | - | | `TUCO_API_KEY` | Yes | — | Your workspace API key (`tuco_…`). | | `TUCO_API_URL` | No | `https://app.tuco.ai` | API base URL. Override only if Tuco support points you at a different environment. | Equivalent flags: `npx tuco-mcp --api-key tuco_your_api_key --api-url https://app.tuco.ai` > [!NOTE] > > Your API key is tied to one workspace **and** one environment — the `TUCO_API_URL` must match the environment the key was issued for. ## Available Tools | Tool | Description | | - | - | | `send-imessage` | Send to a phone or email, with scheduling and a send window (hours, timezone, days of week) — [fields](/api-reference/endpoint/send-message) | | `add-lead` | Add a new contact to your workspace | | `check-imessage` | Check if a number has iMessage | | `get-replies` | List replies, filterable by lead, phone, line and date | | `list-conversations` | Browse inbox conversations (e.g. those needing a reply). Group chats have `isGroup: true` | | `suggest-reply` | Draft AI reply options for a conversation | | `send-reply` | Send a reply within a conversation — also into a group chat, using its `group:…` id | | `lines-health` | Monitor all sending line health status | | `check-limits` | View line limits and current usage | | `create-line-request` | Order a new line. Legal name, company name and anti-spam acceptance are mandatory; an eSIM order also needs the legal address, `simCountry` and the ZIP to provision on ([fields](/api-reference/endpoint/create-line-request)). `reviewOnly: true` validates and previews without creating | | `get-line-request` | Poll a line request by id until it is provisioned | | `check-health` | Verify API connection status | | `list-dnc` | List Do-Not-Contact entries; `since` returns new opt-outs (STOP replies) oldest first | | `check-dnc` | Check whether a phone or email is on the Do-Not-Contact list | | `add-to-dnc` | Add one phone or email to the Do-Not-Contact list | | `bulk-add-to-dnc` | Add up to 10,000 phones/emails at once | | `create-webhook` | Subscribe a URL to events such as `message.reply` or `dnc.added` | | `send-test-webhook` | Send a test delivery identical to a live one ([variants](/api-reference/endpoint/send-test-webhook)) | | `list-webhook-deliveries` | Read the delivery log; `replay-webhook-delivery` re-sends one | This is a selection — the server exposes 96 tools. Your MCP client's tool browser lists them all. ## Example Prompts Once connected, just talk to your AI assistant: * "Send an iMessage to +12125551234 saying Hey, wanted to follow up on our call" * "Check if +19045551234 has iMessage enabled" * "Show me all conversations that need a reply" * "Draft and send a reply to the latest message from +15551234567" * "How are my sending lines doing?" * "Show me the last 5 unread replies" * "Add a lead: John Doe, +15551234567, CEO at Acme Corp" * "Who replied STOP since yesterday? List their numbers" * "Is +15551234567 on our Do-Not-Contact list?" ## Supported Clients * Claude Desktop * Cursor * Windsurf * Any MCP-compatible AI client ## Source Code [View on npm](https://www.npmjs.com/package/tuco-mcp) # n8n Workflows Source: https://docs.tuco.ai/integrations/n8n Download pre-built n8n workflow templates for Tuco, personalized with your API key, for CRM sync, reply routing and outbound iMessage follow-ups. Tuco provides pre-built n8n workflow templates to connect your iMessage platform with CRMs, notification tools, and custom logic. ## Available Templates | Template | Description | | - | - | | **Unified Workflow** | All-in-one: send messages, handle replies, update CRM | | **Flow A — Outbound** | Send initial outreach messages to leads | | **Flow B — Follow-up** | Automated follow-up sequence on no reply | | **Reply Handler** | Route incoming replies to your CRM or webhook | ## Download Templates 1. Go to **API Keys** → **n8n Templates** tab in the [dashboard](https://app.tuco.ai/api-keys) 2. Click **Download** on any template 3. Templates are personalized with your API key and domain > [!NOTE] > > You'll still need to add your CRM credentials (HubSpot, GHL, etc.) in n8n after importing. ## Import into n8n 1. Open your n8n instance 2. Go to **Workflows** → **Import from File** 3. Select the downloaded JSON template 4. Review the nodes and add missing credentials 5. Activate the workflow ## Template Structure ### Unified Workflow * **Trigger**: Webhook from Tuco (message events) * **Router**: Split by event type (sent, reply, fallback) * **CRM Update**: Update contact in HubSpot/GHL * **Notification**: Post to Slack or send email alert * **Fallback**: Trigger SMS via Twilio for non-iPhone contacts ### Flow A — Outbound * **Trigger**: New lead added (via webhook or schedule) * **Lookup**: Check if lead has iMessage * **Send**: Send personalized outreach via Tuco API * **Log**: Record send in CRM ### Flow B — Follow-up * **Trigger**: Scheduled (daily check) * **Filter**: Leads with no reply after 48h * **Send**: Follow-up message via Tuco API * **Update**: Mark lead as "followed up" in CRM ### Reply Handler * **Trigger**: Webhook `message.reply` event * **Classify**: AI classification (interested / not interested / question) * **Route**: Update CRM tag, notify team, or trigger response # Telegram Bot Source: https://docs.tuco.ai/integrations/telegram-bot Connect the Tuco Telegram Bot (@TucoAIBot) to get real-time reply alerts, approve AI drafts and send iMessages from your phone. Connect the Tuco Telegram Bot to manage your iMessage workspace from your phone. ## Setup 1. Go to **API Keys** → **Telegram** tab in the [dashboard](https://app.tuco.ai/api-keys) 2. Click **Connect Telegram** — opens [@TucoAIBot](https://t.me/TucoAIBot) in Telegram 3. The bot auto-links to your workspace > [!NOTE] > > Each workspace can connect to one Telegram chat. To change, disconnect and reconnect. ## Commands ### `/whoami` Returns your workspace info: name, plan, active lines, team members. ### `/send +phone message` Sends an iMessage directly from Telegram. ``` /send +19045551234 Hey, wanted to follow up on our call yesterday ``` The message is sent through your first active line. ### Reply to Notification When you receive an inbound reply notification, just reply to that Telegram message — your reply is sent as an iMessage to the lead. ## What Gets Sent to Telegram | Notification | When | | - | - | | Reply alerts | Lead replies to your iMessage (name, phone, message preview) | | KB draft approvals | AI drafts a reply in Co-pilot mode (Approve/Reject buttons) | | Onboarding events | New user signs up, submits goals | | Billing events | Checkout started, subscription changes | ## Knowledge Base Approval Flow When using the KB in **Co-pilot mode** with Telegram as your approval channel: 1. Lead sends a message 2. AI drafts a reply with a confidence score 3. You receive the draft in Telegram with **Approve** and **Reject** buttons 4. Tap **Approve** to send, **Reject** to discard 5. Or reply with edited text to send a modified version ## Disconnecting Go to **API Keys** → **Telegram** tab → **Disconnect**. This removes the link between your workspace and Telegram chat. # Webhooks Source: https://docs.tuco.ai/integrations/webhooks Receive real-time HMAC-SHA256-signed webhook events from Tuco when messages are sent, replied to or fail. Setup, payloads and signature checks. Tuco sends HTTP POST requests to your endpoint when message events occur. All payloads are signed with HMAC-SHA256. ## Setup 1. Go to **API Keys** → **Webhooks** tab 2. Click **Add Webhook** 3. Enter your endpoint URL 4. Save the generated webhook secret ## Events | Event | Description | | - | - | | `message.sent` | iMessage successfully delivered | | `message.failed` | Delivery failed (recipient may not have iMessage) | | `message.fallback` | iMessage unavailable — route to SMS provider | | `message.reply` | Lead replied to your message | | `message.opened` | Email message opened (email lines only) | ## Payload Structure ```json theme={null} { "event": "message.reply", "timestamp": "2026-04-15T12:00:00Z", "workspaceId": "org_abc123", "data": { "messageId": "msg_xyz789", "recipientPhone": "+19045551234", "message": "Yes, I'm interested!", "status": "received", "lineId": "line_001", "firstName": "Jane", "lastName": "Smith", "attachmentUrls": [], "attachmentNames": [] } } ``` ## Headers | Header | Description | | - | - | | `X-Tuco-Signature` | HMAC-SHA256 hex digest of the JSON body | | `X-Tuco-Event` | Event type (e.g., `message.reply`) | | `X-Tuco-Timestamp` | ISO 8601 timestamp | ## Signature Verification ```javascript theme={null} const crypto = require('crypto'); function verifyWebhook(body, signature, secret) { const expected = crypto .createHmac('sha256', secret) .update(JSON.stringify(body)) .digest('hex'); return signature === expected; } ``` > [!WARNING] > > Always verify the signature before processing webhook payloads. Reject requests with invalid signatures. ## Testing Click the **Test** button next to any webhook in the dashboard. Tuco sends a test payload with `testMode: true` and shows you the response status + latency. ## Retry Policy Tuco does not retry failed webhook deliveries. If your endpoint returns a non-2xx status, the event is logged but not resent. Use the **Test** button to verify your endpoint is reachable before going live. ## Common Patterns **Customer.io:** point these webhooks at a webhook-triggered Customer.io journey and record each one as an event on the person. See [Send iMessage from Customer.io](/guides/send-imessage-from-customer-io). ### SMS Fallback ```javascript theme={null} if (event === 'message.fallback') { // Recipient doesn't have iMessage — send SMS via Twilio await twilio.messages.create({ to: data.recipientPhone, from: '+1YOURTWILIONUMBER', body: data.message, }); } ``` ### CRM Update ```javascript theme={null} if (event === 'message.reply') { // Update HubSpot contact with reply await hubspot.crm.contacts.basicApi.update(contactId, { properties: { last_reply: data.message, last_reply_date: data.timestamp } }); } ``` # Limits & Constraints Source: https://docs.tuco.ai/limits The technical limits that shape how Tuco sends: line activation time, first-message rules, per-line caps, bans, reaching Android, and what Tuco can't do. **Tuco sends real iMessage from real Apple hardware, so it inherits Apple's rules — these are the hard constraints to plan around.** This page is a quick operational reference; each row links to the detailed doc. For the full plain-English rundown of *why* each limit exists, see [tuco.ai/limitations](https://tuco.ai/limitations). ## The constraints at a glance | Constraint | What it means | Details | | - | - | - | | **Line activation takes \~48h** | A new line runs on a real Apple device + carrier eSIM that the carrier must activate first. Budget 48h+ from order to first message. | — | | **First-message rules** | On the first-ever message to a contact, links aren't clickable and you can't send an attachment/voice note. Send a plain text first; once they reply, everything works. | [Send messages](/features/send-messages) | | **Per-line sending caps** | **50 new contacts/day** per line (the maximum, it can't be raised) and **150 total messages/day** by default (you can raise it in **Lines → Edit**, but that voids your free first replacement), plus pacing: new contacts at most **5/min and up to 49/hour**, other messages at most **10/min and 40/hour**, with burst spacing. Held messages (daily cap, line offline) are released gradually, never as a burst. Need more new contacts? Add a line. | [Rate limits](/features/rate-limits) | | **Every message can be reported** | Until a lead saves you or taps Mark as Known, Apple shows "Maybe: your name" with Delete and Report Spam on **every** message, not just the first. No old or forgotten leads, no high-pressure tactics, **no more than 4 follow-ups** to someone who hasn't replied; re-engage older leads with a different message each and 3–5 minutes between leads. | [What your leads see](/what-leads-see) | | **Line info: 3 changes a month** | A line's display name and photo can change at most **3 times per line per month** — each change needs a person on our side to update the Mac. Ordering doesn't count, and every update response shows how many are left. The 4th returns `400`; contact support. Review everything before you order. | [Update a Line](/api-reference/endpoint/update-line) | | **Bans are a switch, not a score** | About **5** "Report Junk" taps can **permanently** ban a line — regardless of your send rate. Apple doesn't notify anyone when you're reported, so there's no count to watch. Only message people who opted in. | [Line health](/troubleshooting/line-health-and-restrictions) | | **Porting takes 3–7 business days** | We can port in your existing number, but it takes a minimum of 3–7 business days, so a fresh number gets you live sooner. A banned number can't be recovered — only replaced with a new one. Don't print a line on business cards. | — | | **Android needs a second channel** | iPhone contacts get iMessage, which works globally. Android contacts need either **P2P SMS** — the line texts them from its own number, **only to recipients in the eSIM's country** — or an SMS provider you connect. P2P SMS is off by default; ask support to enable it per line. | [Reach Android contacts](/guides/reach-android-contacts-p2p-sms) | | **Availability checks are capped** | Tuco can check **\~70 numbers/line/day** for iMessage support — enough for routing new leads, not for scanning a large list. | [Check availability](/guides/check-imessage-availability) | | **One line = one identity** | Reps can share a line for outbound calls, but the contact card and forwarding are fixed per line — no per-rep identity switching. | — | | **Calling** | Included: 500 outgoing min/line/month with recording, unlimited incoming, \$3 per extra 100 min. Regular calls can show "Potential spam" until the lead saves you. The FaceTime Audio add-on and the Registered caller ID add-on avoid it. | [Calling](#calling) | | **FaceTime Audio is an add-on** | FaceTime Audio calling is available as a **\$100/mo per line** add-on. Regular calls on the same number are included. | — | | **Group chats are included** | Your line replies inside existing iMessage group chats — **free** on every plan. Starting a brand-new group from Tuco isn't supported. | — | | **No HIPAA** | Apple won't sign a BAA for iMessage, so Tuco **can't** be HIPAA compliant. Never send protected health information (PHI). Booking/reminders are fine; medical detail is not. | — | ## A few that trip people up ### Calling Every phone line includes **500 outgoing minutes per month** (pooled across your phone lines) with **call recording**, **unlimited incoming calls** forwarded to one number in the **same country as the eSIM**, and extra minutes at **\$3 per 100**. Regular calls go out through Telnyx using your line's number as caller ID. The person you call may see **"Potential spam"** unless they saved your number or tapped "Mark as known" — text them first, before you call. Why: carriers grade each call with a **STIR/SHAKEN** attestation, and because Telnyx can't own the number your line uses for iMessage, calls are attested **B** rather than **A**. This is industry-wide, not a Tuco limit: every iMessage provider, Sendblue included, calls from an iMessage number with B. An **A** attestation needs a number the calling carrier owns, and those numbers can only do SMS, not iMessage. | Add-on | Price | What it does | | - | - | - | | **FaceTime Audio add-on** | \$100/mo per line | Calls go over FaceTime, so there's no carrier spam label. Costs more because it needs different hardware than iMessage. | | **Registered caller ID add-on** | $50 setup + $50/mo per line + \$0.075 per call | A separate, fully-attested calling number registered with carriers that shows your business name (US-to-US calls to T-Mobile and Verizon mobiles). Calls come from that number, not your iMessage number. No FaceTime Audio needed. | Add-ons are picked at checkout (for every phone line in your plan, charged with your plan) or per line later (charged to your card on file). An add-on paid at checkout is added to each phone line you order automatically, with no new charge. Registered caller ID also needs your business details before it can go live — see [Registered caller ID setup](/features/registered-caller-id). **Once bought they can't be removed** — contact [support@tuco.ai](mailto:support@tuco.ai) to change them. Changing your plan keeps them. See [Calling & Add-ons](/features/calling-add-ons). ### iMessage doesn't blast The per-line caps exist because iMessage rewards personal, opt-in sending and punishes volume. Tuco is a **speed-to-lead** tool — reach people the moment they raise their hand (form fills, ad opt-ins, hot inbound). To scale, add lines; don't push one line harder. See [line health & restrictions](/troubleshooting/line-health-and-restrictions). ### Bans and replacements If a line is banned, you get a free replacement on the first occurrence; the 2nd and 3rd replacements cost **\$50** each, and on the 4th ban we part ways. Raising a line's daily total above 150 voids the free first replacement. A banned number can't be recovered — only replaced. Treat every line as a working sender that could one day need swapping, not a forever number. ### No PHI, ever Because Apple won't sign a BAA, no service built on iMessage — Tuco included — can be HIPAA compliant. Clinics and medspas can use Tuco for booking and reminders, but never for diagnoses, records, or any medical detail. ## Frequently asked questions > [accordion] How many iMessages can I send per day? > > Per line: 50 new-contact sends per day (the maximum, it can't be raised) and 150 total sends per day by default. Sends are paced (new contacts at most 5 a minute and up to 49 an hour, other messages at most 10 a minute and 40 an hour) so a line never bursts. You can raise total sends in **Lines → Edit**, but doing so voids your free first replacement. Send no more than 4 follow-ups to someone who hasn't replied. To reach more new contacts, add lines: each one adds another 50 a day. See [rate limits](/features/rate-limits). > [accordion] Can Tuco blast a big cold list? > > No — by design. iMessage penalizes high-volume cold sending with permanent bans, so Tuco caps each line and is built for personalized, opt-in, speed-to-lead outreach. See [line health](/troubleshooting/line-health-and-restrictions). > [accordion] Can I bring my own phone number? > > Yes. We can port in your existing number; it takes a minimum of 3–7 business days, so a fresh number is faster. If a line is ever banned it's replaced with a new number (the old one can't be recovered). > [accordion] Is Tuco HIPAA compliant? > > No, and it never can be — Apple won't sign a BAA for iMessage. Don't send protected health information. Appointment booking and reminders are fine; medical detail is not. > [accordion] How do I reach Android users? > > Two ways, and the simple one does **not** involve A2P 10DLC. > > **P2P SMS (recommended).** The line sends the text itself, from its own number, through the iPhone paired to it. Same number, same thread — the contact just sees a green bubble. It's person-to-person traffic, so there is no brand or campaign registration. It is **off by default**; ask support to turn it on for a line. > > **A connected SMS provider.** Twilio, Telnyx or GoHighLevel, from a separate number you own. This one *is* application-to-person, so US traffic needs A2P 10DLC registration — that requirement comes from the carriers, not from Tuco. > > You can also just message iPhone contacts and skip both. > [card] [Rate limits & sending caps](/features/rate-limits) > > The exact per-line daily and hourly caps, and which ones you can change. # Operations Runbook Source: https://docs.tuco.ai/operations/runbook Step-by-step guidance for diagnosing and resolving common Tuco production issues from your side. Runbook + ops playbooks for Tuco AI iMessage automation on. ## Purpose of This Runbook This runbook is for **your** on‑call engineers, SREs, and operators. It assumes: * You use Tuco only via documented public APIs and webhooks. * You rely on Tuco’s UI, APIs, and events—not its internal services or logs. The goal is to give you **practical, observable steps** for common situations, without exposing any proprietary implementation details. *** ## 1. Messages Not Sending as Expected ### Symptom * Sends look scheduled, but: * Few or no new messages appear as **sent/delivered**. * You see fewer Tuco message webhooks in your systems than expected. ### Checks 1. **Are you actually creating messages?** * In Tuco: * Check the Messages view: * Do you see new messages appearing with early statuses (for example, queued)? * In your own data: * If you mirror messages, confirm that new records are being created when you call Tuco. 2. **Are you within your own configuration limits?** * In Tuco: * Look at the lines used for these sends: * Are they active? * Do you see any warnings about limits or availability? 3. **Are time windows and days configured as you expect?** * Confirm: * That current time is within allowed hours. * That today is an allowed day for sending. 4. **What do webhooks show?** * In your logs: * Check whether: * Outcome webhooks (delivered / fallback / failed) are still arriving. * Their volume has recently dropped. ### Actions * **If messages are not even being created:** * Inspect your integration: * Are API calls to Tuco failing? * Have you recently changed authentication or endpoints? * **If messages are created but stay queued:** * Treat this as a sign that limits or timing rules are keeping them on hold. * Consider: * Adding more lines. * Adjusting windows or pacing, if appropriate. * **If message creation and queuing look normal but nothing progresses:** * Check any Tuco status communication you have (for example, a status page). * Contact Tuco support with: * A small set of message IDs. * Rough timestamps and workspace IDs. *** ## 2. High Rate of Failed Messages ### Symptom * Many messages in a workspace show status **failed**. * Your dashboards or exports show a spike in failures. ### Checks 1. **Sample failed messages** * In Tuco: * Open a few failed messages and read the visible reason text. * Look for patterns: * Invalid addresses? * Blocked or rejected by channel? 2. **Segment by source** * Are failures concentrated in: * A particular list or import? * A specific integration (for example, a given CRM connector)? 3. **Check recent changes** * On your side: * Did you recently change your data import, normalization, or validation? * In your messaging strategy: * Did you change templates, targeting, or types of messages? ### Actions * **If failures are caused by bad data:** * Clean or suppress invalid email addresses or phone numbers. * Tighten validation and normalization in your upstream systems. * **If failures align with a particular segment:** * Pause or reduce volume for that segment. * Investigate whether the content or targeting is causing issues on the recipient side. * **If failures are broad and unexpected:** * Use your webhook and API logs to gather: * Example message IDs. * Visible reason texts. * Share that sample with Tuco support for deeper investigation. *** ## 3. Many Fallback Events ### Symptom * You see many messages with status **fallback** or many `fallback`‑style events in webhooks. * Outreach relying heavily on iMessage appears to be under‑delivering. ### Checks 1. **Interpret what fallback means for your setup** * In general, fallback indicates: * The primary channel (e.g. iMessage) isn’t available or appropriate. * It does **not** by itself mean Tuco is down. 2. **Review data quality** * Are phone numbers: * Stored in an appropriate format (for example, E.164)? * Using correct country codes? * Are email addresses valid and mapped correctly? 3. **Segment by source** * Are fallbacks concentrated: * In a particular import or list? * For a region or provider? ### Actions * **Improve data quality** * Normalize phone numbers and emails. * Ensure the most reliable addresses are stored as primaries. * **Adjust channel strategy** * For segments with consistently high fallbacks: * Prefer SMS or email as the primary channel. * Reserve iMessage for those with confirmed availability. Use `/features/check-availability` to periodically refresh your view of who can actually be reached via iMessage. *** ## 4. Webhooks Not Reaching Your Systems ### Symptom * You stop seeing Tuco webhooks in your logs. * Your downstream automations or dashboards stop updating. ### Checks 1. **Verify your endpoint health** * Confirm: * The URL configured in Tuco is correct. * Your endpoint is reachable via HTTPS from the public internet. * Use your own health checks where possible. 2. **Check your logs** * Look for: * Any inbound requests from Tuco. * HTTP status codes your endpoint is returning. * Timeouts or rate‑limit defenses on your side. 3. **Authentication** * Make sure: * Any shared secrets or API keys used for webhook auth are up to date. * Recent rotations are reflected both in Tuco’s settings and your code. ### Actions * **If your endpoint is the problem:** * Fix underlying issues (deployment problems, certificate issues, firewall changes). * Once stable, re‑enable or reconfirm webhook configuration in Tuco. * **If you changed authentication:** * Align Tuco’s configured secret/token with what your endpoint now expects. * **To improve resilience going forward:** * Use a lightweight ingress layer that: * Authenticates and validates requests. * Quickly enqueues them to an internal queue. * Responds with success before heavy processing. *** ## 5. Read‑Only or Billing‑Related Errors ### Symptom * API writes begin failing with codes or messages indicating **read‑only** or billing issues. * New messages or leads are not being created, even though reads still work. ### Checks 1. **Inspect error responses** * In your logs: * Confirm that responses from Tuco explicitly mention a read‑only or billing state. 2. **Determine scope** * Identify: * Which workspace(s) are affected. * Whether dev/stage/prod are all impacted or just one environment. ### Actions * **Operationally** * Stop automated retries for writes to the affected workspace; they will continue to fail until resolved. * If you surface Tuco‑driven features in your own UI, show a clear message to internal users such as “Messaging is temporarily disabled; please update billing in Tuco.” * **Remediation** * Have a Tuco admin or billing owner: * Resolve any outstanding billing issue in the Tuco app. * Once resolved: * Verify that new messages and leads can again be created successfully. *** ## 6. Debugging a Specific Lead or Conversation ### Symptom * A particular contact’s journey looks wrong: * Missing steps. * Unexpected status changes. * Replies not appearing where you expect. ### Checks 1. **Trace the history in Tuco** * In the Tuco UI: * Open the lead or conversation view. * List all messages in order with their statuses and timestamps. 2. **Compare with your own systems** * In your CRM or backend: * Confirm that: * Your records match Tuco’s message history. * You have (or have not) ingested the associated webhooks. 3. **Look for configuration differences** * For the relevant templates or workflows, confirm: * Time windows, days, and limits. * Whether replies should stop further follow-ups. ### Actions * **If the discrepancy is on your side:** * Fix your webhook consumer, data mapping, or UI. * **If the discrepancy appears to be in Tuco:** * Gather: * Workspace ID (if available). * Lead identifier. * A handful of message IDs and timestamps. * Share this context with Tuco support for further investigation. *** ## 7. General Best Practices for Operations * **Prefer clear contracts over internal details** * Rely on: * Documented APIs. * Webhook schemas. * Status codes and visible outcomes. * Avoid depending on assumptions about Tuco’s internal workers, queues, or file layouts. * **Design for idempotency and eventual consistency** * Treat every webhook or API response as something that might arrive twice or slightly out of order. * Always reconcile against current state where possible. * **Monitor what you can see** * Build dashboards and alerts around: * Message outcome distributions. * Webhook delivery success/failure. * Tuco API error codes. * **Document your own playbooks** * Use this runbook as a starting point and: * Add environment‑specific steps. * Add contact information for your internal owners. * Add links to your own status pages and tooling. These practices let you run Tuco as a dependable piece of your stack, using only the stable, customer‑visible interfaces and without any dependence on proprietary implementation details. # Pricing, Plans & AI Credits Source: https://docs.tuco.ai/pricing Tuco AI pricing: Starter $149/mo, Growth $299/mo, the $335 setup fee, extra lines, calling add-ons, AI credits, credit packs and billing rules. **Tuco has two self-serve plans: Starter at $149/month with 1 phone line, and Growth at $299/month with 2 phone lines. Each plan has a one-time \$335 setup fee. Teams that need 6 or more lines get Enterprise pricing.** All prices are in USD and were current as of October 2026. ## Plans | | **Starter** | **Growth** | **Enterprise** | | - | :-: | :-: | :-: | | Monthly price | **\$149/mo** | **\$299/mo** | Custom | | One-time setup | \$335 | \$335 | Custom | | First charge | \$484 | \$634 | Custom | | Phone lines included | 1 | 2 | Custom | | New contacts / day | 50 | 100 (50 per line) | Negotiated | | Total messages / day | 150 | 300 (150 per line) | Negotiated | | Calling minutes included | 500 / mo | 1,000 / mo (500 per line) | Custom | | AI credits / month | 25,000 | 75,000 | Custom pool | | Extra phone lines | Not available. Upgrade to Growth | $149/mo + $335 setup each | Custom | | Email lines | \$60/mo each | \$60/mo each | Custom | | CRM integrations | All | All | All, plus custom | | Group chats | Included (free) | Included (free) | Included (free) | | FaceTime Audio | \$100/mo add-on | \$100/mo per line add-on | \$100/mo per line add-on | | Support | Email | 4-hour SLA | 24/7, dedicated manager | Every plan includes the full product: campaigns, sequences, AI replies, the Knowledge Base, CRM sync, webhooks, the API and the MCP server. Plans differ in how many lines you get, how much you can send, how many AI credits you get, and the level of support. > [!NOTE] > > You don't buy or host any hardware. Every line runs on a real iPhone and eSIM that we keep in our facility. The setup fee pays for that hardware, and if a device or Apple ID fails, replacing it is our job. ### Daily sending limits The daily limits are **per line**. Each line can message 50 contacts for the first time per day, and send 150 messages per day in total, including follow-ups. Growth's 100 and 300 are those per-line numbers multiplied by its 2 lines. To send more, add lines rather than pushing one line harder. 50 new contacts a day is the maximum on any line; total messages can be raised in line settings, but that voids your free first replacement. See [Rate limits](/features/rate-limits) and [Limits & constraints](/limits). ## The setup fee The **\$335 one-time setup fee** pays for a real iPhone and its eSIM for the line. It is charged once: * **Starter:** \$335 for its 1 line. * **Growth:** \$335 for its 2 included lines. * **Each extra phone line:** another \$335. If you cancel and come back later, you don't pay setup again for the same lines. Email lines have no setup fee. ## Adding lines * **Extra phone lines** are available on **Growth**, at **$149/month plus $335 setup** per line. When you add a line, we charge the setup fee and a prorated monthly amount for the rest of your billing period. After that, the line renews with your plan. Starter includes only 1 phone line, so upgrade to Growth to add another. * **Email lines**, which send iMessage from an iCloud email address, cost **\$60/month each** on Starter or Growth, with no setup fee. * **Online checkout covers 1 to 5 lines.** For 6 or more lines, [book a call](https://tuco.ai/demo). We'll set you up on Enterprise pricing. You order lines from the **Lines** page in the dashboard, or with the [Create Line Request](/api-reference/endpoint/create-line-request) API. ## Calling Every phone line can make and receive calls on the same number it texts from, at no extra cost: * **500 outgoing minutes per phone line per month**, shared across all your phone lines, with call recording. * **Unlimited incoming calls**, forwarded to one number in the same country as the line's eSIM. The included minutes reset on the 1st of each month (UTC). If you run out, outgoing calls stop until you buy more minutes or the month resets. Minute packs never expire: | Minute pack | Price | Per minute | | - | - | - | | 100 minutes | \$3 | \$0.030 | | 500 minutes | \$12 | \$0.024 | | 2,000 minutes | \$40 | \$0.020 | ### Calling add-ons | Add-on | Price | What it does | | - | - | - | | **FaceTime Audio** | \$100/mo per line | Calls go over FaceTime Audio from the same Apple identity that texts the lead, so carriers don't add a "Potential spam" label. | | **Registered caller ID** | $50 setup + $50/mo per line + \$0.075 per call | Gives the line a separate calling number, registered with carriers, that shows your business name on US calls to T-Mobile and Verizon mobiles. | You can choose add-ons at checkout, or per line later: * **At checkout**, an add-on is bought for every phone line in your plan and charged with your plan. Each phone line you order after that gets it automatically, with **no new charge**. * **Later**, from **Lines → Calling** or when you add a line, it's charged to your card on file: the setup fee plus a prorated share of the monthly price for the rest of your billing period. If you still have an unused add-on from checkout, that one is used first, at no charge. Registered caller ID also needs a few business details before it can go live. See [Registered caller ID setup](/features/registered-caller-id). Once bought, an add-on can't be removed from the dashboard. Email [support@tuco.ai](mailto:support@tuco.ai) to change one. To learn more, see [Calling & Add-ons](/features/calling-add-ons). To learn why regular calls can show "Potential spam", see [Limits: Calling](/limits#calling). For the add-ons API, see [Calling add-ons](/api-reference/endpoint/calling-addons). ## AI credits AI credits pay for the AI work Tuco does in your workspace. **1 credit = 1,000 tokens**, counting input and output together. **What uses credits:** * **AI replies.** These are Knowledge Base auto-replies and goal bots, in copilot or autopilot mode. Each reply uses about **13 credits** on average, because it includes context from your knowledge base. * **Knowledge Base indexing.** Adding a document or website page uses about **8–9 credits** per item. * **AI writing**, such as campaign and sequence generation, the copywriter, and per-message personalization. * **Suggested replies** in the inbox, which use well under 1 credit each. **What doesn't use credits:** classifying replies as interested or not interested, and sending messages. As a rough guide, Starter's 25,000 monthly credits cover about **1,900 AI replies**, and Growth's 75,000 cover about **5,800**. ### How credits reset * Your plan's monthly credits **reset on the 1st of each month (UTC)**. Unused plan credits don't roll over. * You can see your balance in the **AI battery** icon in the dashboard header. ### Credit packs If you need more credits, buy a one-time pack from the **Billing** page. Pack credits are added right away, **never expire**, and are used only after your monthly plan credits run out. | Pack | Price | Per 1,000 credits | About this many AI replies | | - | - | - | - | | 10,000 credits | \$5 | \$0.50 | 770 | | 50,000 credits | \$20 | \$0.40 | 3,850 | | 100,000 credits | \$35 | \$0.35 | 7,700 | ### When you run out We email you when you've used **80%**, **95%** and **100%** of your credits. If you run out of credits completely: * **AI auto-replies pause.** Inbound replies are still received, and we email you so that you can answer them yourself. * **AI writing tools stop working** until you buy a pack or your credits reset. * **Sending is not affected.** Campaigns, sequences and manual messages keep going out. ## Annual billing Annual billing is **20% off** the monthly price. Starter costs $1,430.40 a year (about $119/mo), and Growth costs $2,870.40 a year (about $239/mo). Setup fees stay the same. To switch to annual, contact [support@tuco.ai](mailto:support@tuco.ai) or your account manager. ## Changing or cancelling your plan * **Upgrading** takes effect immediately. We charge the difference, prorated, for the rest of your billing period. * **Downgrading** takes effect at your next renewal. * **Add-ons stay on your lines** when you change plans. * **Cancel anytime** from the **Billing** page. There is no long-term contract, and cancelling stops all future charges. * **Invoices and receipts** are in the Stripe billing portal, which you open from the **Billing** page. * **If a payment fails**, your workspace goes into read-only mode until the payment goes through. See [Security, access & billing](/faq/security-billing). > [!WARNING] > > **No refunds or returns.** Setup fees and every monthly or annual payment are final once paid. Cancelling stops future charges only. We don't refund partial billing periods, unused time, setup fees or earlier payments. We also don't offer free trials, paid pilots or money-back guarantees. [Book a demo](https://tuco.ai/demo) and ask every question you have before you buy. ## Enterprise and agencies If you need 6 or more lines, custom routing, white-label options or a custom AI-credit pool, or you run several client workspaces, you'll get custom volume pricing. [Book a call](https://tuco.ai/demo) to get started. Agencies can create and manage client workspaces with the [Agency API](/api-reference/agency-api-keys). ## The Mini plan (retired) We stopped selling the Mini plan, which had 1 email line and no phone line, to new customers on **July 18, 2026**. If you're already on Mini, you keep your plan and price. To add lines, upgrade to Starter. ## Frequently asked questions > [accordion] How much does Tuco cost? > > Starter costs $149/month with 1 phone line, and Growth costs $299/month with 2 phone lines. Each has a one-time $335 setup fee, so your first charge is $484 on Starter or $634 on Growth. Each extra phone line on Growth costs $149/month plus \$335 setup. > [accordion] Why is there a setup fee? > > Each phone line runs on a real iPhone with its own eSIM, which we buy and host for you. The \$335 pays for that hardware. You pay it once per line, not every month, and you don't pay it again if you cancel and come back. > [accordion] Is there a free trial? > > No. We don't offer free trials, paid pilots or refunds. [Book a demo](https://tuco.ai/demo) to see the product before you buy. > [accordion] Do AI features stop working when I run out of credits? > > AI auto-replies and AI writing tools pause until you buy a credit pack or your monthly credits reset on the 1st. Messages keep sending, and we email you about any inbound replies that need a human answer. > [accordion] Do purchased credits or minutes expire? > > No. Credit packs and minute packs last until you use them. Only your plan's monthly credits and included minutes reset each month. > [accordion] Can I add more lines later? > > Yes, on Growth. Each extra phone line costs $149/month plus a $335 setup fee. Email lines cost \$60/month on Starter or Growth. If you need 6 or more lines, [book a call](https://tuco.ai/demo) for volume pricing. > [accordion] Do I need A2P 10DLC registration? > > No, not for iMessage. iMessage doesn't go through carrier A2P registration. You'd only need it if you connect your own SMS provider to reach Android contacts. See [Reach Android contacts](/guides/reach-android-contacts-p2p-sms). # Quick Start Source: https://docs.tuco.ai/quickstart Get started with Tuco AI in under 5 minutes. Tuco AI is the iMessage automation platform for B2B and B2C teams — dedicated Apple hardware, CRM-native, no A2P. ## Welcome to Tuco AI! 🎉 This guide will help you upload your first leads, check iMessage availability, and send your first message in just a few minutes. *** ## Prerequisites Before you begin, make sure you have: > [!TIP] > > Active Tuco AI account - [Sign up here](https://app.tuco.ai/signup) > [!TIP] > > CSV file with leads (optional - we'll show you how to create one) > [!TIP] > > Messaging line configured (we'll guide you through this) *** ## How Tuco works (read this first) > [!NOTE] > > A few things up front prevent the most common surprises: > > * **You don't need your own Mac.** Tuco hosts the Apple-connected sending line for you. > * **Recipients must be on iMessage to get a blue bubble.** Tuco checks availability first and routes everyone else to your SMS fallback — set one up under **Settings → When iMessage isn't available**. > * **New lines warm up, and each line has daily send caps.** Volume ramps over time and scales by adding lines — Tuco won't let you blast (blasting is what gets lines restricted). > * **"Sent" is not "Delivered".** `sent` means Tuco handed the message to iMessage; delivery confirmation is separate. See [message statuses](/troubleshooting/message-statuses). > * **iMessage should be triggered, not blasted** — personalized, event-driven sends to contacts who opted in. *** ## Step 1: Set Up Your First Line A "line" is your messaging channel. You need at least one active line to send messages. **1. Navigate to Lines** Log in and go to **Settings → Lines** **2. Purchase or Configure Line** Click **Add Line** and follow the setup wizard **3. Verify Server URL** Ensure your line has a valid Server URL and shows as **Active** > [!NOTE] > > **First-time setup:** Your first line configuration may take 2-3 minutes. You'll receive an email when it's ready. *** ## Step 2: Upload Your First Leads Now let's add some leads to your workspace. ### Option A: Use Sample Template **1. Download Template** Go to **Leads → Import** and click **Download Template** **2. Fill in Sample Data** Add 2-3 sample leads to the CSV: ```csv theme={null} firstName,lastName,email,phone,companyName John,Doe,john@example.com,+12025551234,Acme Corp Jane,Smith,jane@example.com,+12025555678,Tech Inc ``` **3. Upload CSV** Drag & drop the file or click **Choose File** **4. Create List** Name your first list (e.g., "Sample Leads") **5. Map Fields** Review auto-mapped fields and click **Import** ### Option B: Quick Send (No Upload Required) Skip the upload and try Quick Send instead: > [card] [Try Quick Send](#step-4-send-your-first-message) > > Jump to Step 4 to send a message without uploading leads *** ## Step 3: Check iMessage Availability Verify which leads support iMessage before sending. **1. Navigate to Leads** Go to **Leads** page - you'll see your imported leads **2. Auto-Check Running** The system automatically checks availability after upload Watch the status icons: * 🔄 **Checking** - Verification in progress * 🔵 **Available** - Ready to receive iMessage * ⚪ **Unavailable** - Will receive SMS/email instead **3. Manual Re-check (Optional)** Select leads and click **Check Availability** to re-verify > [!TIP] > > **Pro Tip:** Availability checks take 5-10 seconds per lead. The system processes them automatically in the background. *** ## Step 4: Send Your First Message Let's send your first message! Choose your preferred method: > [tab] Quick Send > > **Best for:** Testing or one-off messages > > **1. Open Quick Send** > > Click **Quick Send** button in the top nav > > **2. Enter Recipient** > > Type a phone number with country code: > > `+12025551234` > > **3. Wait for Availability Check** > > System automatically checks if recipient supports iMessage (5 seconds) > > **4. Compose Message** > > Type your message: > > "Hi! This is a test message from Tuco AI." > > **5. Send** > > Click **Send Now** - Your first message is on its way! 🚀 > [tab] Send to Leads > > **Best for:** Organized outreach to your leads > > **1. Select Leads** > > Go to **Leads** page and select one or more leads (checkboxes) > > **2. Open Message Composer** > > Click **Send Message** in the toolbar > > **3. Compose Message** > > Type your message - same for all selected leads > > **4. Choose Delivery** > > * **Send Now** - Immediate delivery > * **Schedule** - Pick date and time > > **5. Send Messages** > > Click **Send** - Messages are sent sequentially > [!TIP] > > **Success!** You've sent your first message with Tuco AI 🎉 *** ## Step 5: Track Your Messages Monitor delivery status and engagement: **1. Open Messages Dashboard** Navigate to **Messages** page **2. View Message Status** See all sent messages with status: * ✅ **Sent** - Successfully delivered * 📅 **Scheduled** - Queued for future * ❌ **Failed** - Delivery error **3. Filter & Search** Use filters to find specific messages: * By status * By date range * By recipient * By message type *** ## Next Steps Now that you've sent your first message, explore these features: > [card] [Import from HubSpot](/features/upload-leads#hubspot-integration) > > Sync contacts automatically from HubSpot > [card] [Schedule Messages](/features/send-messages#scheduling-messages) > > Schedule messages for optimal timing > [card] [Bulk Operations](/features/check-availability#bulk-checking) > > Check availability across your lead list > [card] [API Integration](/api-reference/introduction) > > Build custom integrations with our API *** ## Common Questions > [accordion] How long does availability checking take? > > **5-10 seconds per lead.** The system checks all addresses (phone + email + alternates) and stops at the first available one. Bulk checks are processed sequentially in the background. > [accordion] What happens if iMessage isn't available? > > **Messages automatically fallback to SMS or email.** The system uses the best available delivery method based on your recipient's capabilities. > [accordion] Can I schedule messages for later? > > **Yes!** When composing a message, choose "Send Later" and pick your preferred date and time. Messages are processed by a cron job that runs every minute. > [accordion] How do I know if my message was delivered? > > **Check the Messages dashboard.** Each message shows real-time status: Sent, Failed, Scheduled, or Cancelled. Failed messages include error details. > [accordion] What's the difference between Quick Send and Send to Leads? > > **Quick Send** is for one-off messages without creating lead records (great for testing). > > **Send to Leads** is for organized outreach with full tracking and list management. > [accordion] How many messages can I send at once? > > **Depends on your plan:** > > * Free: 100 messages/day > * Pro: 1,000 messages/day > * Enterprise: Unlimited > > All plans support bulk sending - just select multiple leads! *** ## Need Help? > [card] [Documentation](/features/upload-leads) > > Comprehensive guides > [card] [Email Support](mailto:support@tuco.ai) > > [support@tuco.ai](mailto:support@tuco.ai) > [card] [Community](https://discord.gg/tuco) > > Join our Discord *** ## Quick Tips > [card] ✅ Do > > * Check availability before bulk sending > * Use templates for consistent messaging > * Schedule messages for optimal times > * Export data regularly for backups > [card] ❌ Don't > > * Send without checking availability > * Spam recipients with multiple messages > * Use all caps or excessive punctuation > * Send without consent from recipients *** > [card] [🚀 Ready to scale?](https://app.tuco.ai/pricing) > > Upgrade to Pro for advanced features, higher limits, and priority support # Line Health & Apple Sending Restrictions Source: https://docs.tuco.ai/troubleshooting/line-health-and-restrictions What can restrict or ban a Tuco iMessage line, the warning signs, what Tuco does to protect you, and how to recover — plus how to avoid it. **Apple can throttle or restrict your iMessage line if it behaves like a spam sender — most often from cold, high-volume, identical outreach to people you've never contacted.** A restricted line still *receives* messages and your existing conversations keep working, but Apple stops resolving **new / cold** outbound recipients, so messages to strangers start failing or downgrading. The fix is prevention: keep sends personalized, warmed-up, consented, and triggered — not blasted. ## What a restriction looks like * Messages to **existing conversations** keep delivering normally. * Messages to **new / cold** recipients start failing, downgrading to SMS, or silently not resolving. * You may see a rise in `failed`/`fallback` statuses concentrated on one line. ## What causes it Apple's spam systems react to sender *behavior*, not to Tuco. The main triggers: * **Cold outreach at volume** — messaging many people who never opted in. * **No warm-up** — a brand-new line sending at full volume on day one. * **Identical, templated blasts** — the same message fired to a large list (this is why [iMessage should be triggered, not blasted](/guides/send-bulk-imessage)). * **High daily volume** relative to the line's history. * **Reports** — recipients marking messages as junk. ## What Tuco does to protect you Tuco is built to keep lines healthy: * **Per-line rate limits** and warm-up so one send can't torch a line's reputation ([rate limits](/features/rate-limits)). * **Spam monitoring** that flags rising failure rates as risk before a ban ([spam monitor](/features/spam-monitor)). * **Health checks** that detect a down or degraded line and route around it. * **Availability checks** so you don't burn sends on non-iMessage numbers. ## How to recover A restriction is not always permanent, but recovery is **not instant** and isn't guaranteed: 1. **Stop the risky sending immediately** — pause cold/high-volume outreach. 2. **Reduce volume and warm up** — return to a low, personalized cadence. 3. **Clean your audience** — only message consented, opt-in contacts; honor every STOP. 4. **Contact support** ([support@tuco.ai](mailto:support@tuco.ai)) — we'll review the line and advise on next steps. ## How to avoid it in the first place * **Personalize every message** — no identical mass blasts. * **Trigger sends off events** (new lead, reply, stage change) rather than dumping a static list. * **Warm up new lines** gradually; add lines to scale instead of pushing one harder. * **Only message people who opted in**, and honor opt-outs fast. ## Frequently asked questions > [accordion] Why was my line restricted by Apple? > > Almost always sending behavior that looks like spam — cold, high-volume, or identical messages to people you've never contacted. Apple restricts the line's ability to resolve new/cold recipients while leaving existing conversations working. > [accordion] Is a restricted line permanently banned? > > Not necessarily, but recovery isn't instant or guaranteed. Stop the risky sending, reduce volume, warm up, message only consented contacts, and contact support. > [accordion] How do I avoid getting my line restricted? > > Send personalized, event-triggered messages to consented contacts within your per-line limits, warm up new lines, and never blast identical messages to a big cold list. > [accordion] Will Tuco warn me before a line gets banned? > > Tuco's spam monitor flags rising failure/risk rates and health checks detect degraded lines, so you get early signals — but you're responsible for the sending behavior that drives the risk. > [card] [Bulk iMessage — safely](/guides/send-bulk-imessage) > > Why iMessage should be triggered, not blasted — and how to reach a list without getting flagged. # Why Didn't My Contact Get a Message? Source: https://docs.tuco.ai/troubleshooting/message-not-received Checklist for when a contact wasn't messaged: missing phone, wrong CRM field, not on iMessage, opt-out, line down, daily cap, or a first-message attachment. **If a contact wasn't messaged, it's almost always one of six things: (1) no phone number Tuco can read, (2) the number isn't on iMessage and you have no SMS fallback, (3) the contact opted out / is on your DNC list, (4) the line is paused or restricted, (5) a daily cap deferred the send, or (6) it was a blocked first-message attachment.** Work down this list in order — the first match is usually the cause. ## 1. No recipient — or the phone is in a CRM field Tuco isn't reading The most common cause. If a lead has no phone (or email), the send fails with `missing_recipient`. * **Check:** open the lead in Tuco — is there a phone number on it? * **HubSpot / GoHighLevel:** Tuco reads the standard `phone` field. If your real number lives in a **custom field** (e.g. "Mobile", "Cell", "Phone 2"), map it so Tuco imports it as the phone — see [HubSpot](/guides/send-imessage-from-hubspot) / [GoHighLevel](/guides/send-imessage-from-gohighlevel) mapping. * **Fix:** correct the field mapping and re-sync, or add the number to the lead. ## 2. The number isn't on iMessage and no fallback is set If a contact isn't reachable on iMessage and you haven't configured a fallback, the blue-bubble send has nowhere to go. * **Check:** the lead's [iMessage availability](/guides/check-imessage-availability) — is it ⚪ unavailable? * **Fix:** set your SMS fallback under **Settings → When iMessage isn't available**. In GoHighLevel you can also add the `forcefallback` tag to push a contact to SMS. Without a fallback configured, unavailable contacts are flagged `fallback` but not delivered. ## 3. The contact opted out or is on your DNC list Tuco won't message contacts you've suppressed. * **Check:** the lead for an opt-out flag or DNC entry ([DNC](/features/dnc), [compliance](/guides/imessage-compliance-tcpa)). * **Fix:** this is working as intended — don't message opted-out contacts. Remove from DNC only with fresh consent. ## 4. The line is paused, offline, or restricted * **Check:** [line health](/troubleshooting/line-health-and-restrictions) in the dashboard. * Note the continuity rule: if a line goes offline mid-outreach, contacts that **already** got a message from it have their remaining sends marked `failed` (to preserve the thread); contacts with only queued sends are reassigned to another healthy line. * If Apple has **restricted** the line, new/cold recipients silently stop resolving. See [Line health & Apple restrictions](/troubleshooting/line-health-and-restrictions). ## 5. A daily cap deferred the send (not dropped) Hitting a line's daily limit does **not** drop or fail the message. * **Check:** the message status — is it `queued` or `scheduled`? * **Fix:** nothing. It sends automatically in the next window ([message statuses](/troubleshooting/message-statuses)). Add more lines to raise total daily capacity. ## 6. The first-ever message was an attachment or voice note Attachments (including native voice notes) are **blocked on the first message** to a brand-new contact. * **Fix:** warm the contact up with a plain text message first; the attachment lands on any later step. ## Still shows "sent" but not received? Then it left Tuco fine — the issue is downstream (recipient not on iMessage, line restricted, wrong number, blocked/DND, or a carrier downgrade). See [Message statuses: Sent vs Delivered](/troubleshooting/message-statuses#it-says-sent-but-my-lead-never-got-it). ## Frequently asked questions > [accordion] A contact was skipped entirely — why? > > Usually no readable phone number (or it's in a custom CRM field Tuco isn't mapped to), the contact is opted out / on DNC, or it isn't on iMessage and no fallback is set. Check the lead's phone and availability first. > [accordion] My HubSpot contacts have phones but Tuco says missing\_recipient. > > Tuco reads the standard `phone` field. If your numbers live in a custom property, map that property to phone in Integrations → CRM → Property Mapping, then re-sync. > [accordion] Do daily limits cause contacts to be skipped? > > No. Over-cap sends are deferred to the next window as `queued`/`scheduled`, not skipped or failed. Add lines to increase capacity. > [accordion] Why did my voice note / image not send to a new contact? > > Attachments are blocked on the first-ever message to a contact. Send a text first; attachments work on later messages. > [card] [Message statuses explained](/troubleshooting/message-statuses) > > What sent, delivered, fallback, and failed each mean. # Message Statuses Explained (Sent vs Delivered) Source: https://docs.tuco.ai/troubleshooting/message-statuses What each Tuco message status means — queued, scheduled, sent, delivered, fallback, failed — and why a message can show Sent but not be received. **In Tuco, `sent` means Tuco successfully handed your message to the messaging channel (iMessage / SMS / email) — it does *not* mean the recipient received or read it.** Confirmation that the message reached the device is a separate status, `delivered` (shown where the channel supports it). So a message can correctly read `sent` even if the person hasn't gotten it yet. This page explains every status and what to do with it. ## Every message status | Status | What it means | What to do | | - | - | - | | `queued` | Planned but not yet eligible to send — waiting on allowed hours/days, line capacity, or a step delay. | Nothing — it will send automatically. Normal throttling, not a failure. | | `scheduled` | The line hit its **daily limit**, so the send was deferred (not dropped). Response includes a `scheduledDate` (default 09:00 in the line's timezone next day). | Nothing — treat `201 scheduled` as success. It sends automatically at `scheduledDate`. | | `pending` / `sending` | Actively in flight to the channel right now. | Wait — it resolves to `sent` or `failed` shortly. | | `sent` | Tuco handed the message to the channel per that channel's contract. **Not** a delivery or read confirmation. | Safe to trigger "message sent" workflows. For true delivery, watch for `delivered`. | | `delivered` | Tuco received confirmation the message reached the recipient's device (where the channel supports it). | Use this for true delivery rates and timed follow-ups. | | `fallback` | The recipient isn't reachable on the primary channel (e.g. not on iMessage), so Tuco flagged it for your SMS/email fallback. | Ensure a [fallback is configured](/features/failures-and-fallbacks); tag the lead "not on iMessage". | | `failed` | Tuco determined the message **cannot** be sent (invalid address, hard channel rejection, or a line problem). Not silently retried. | Clean the data or check [line health](/troubleshooting/line-health-and-restrictions). | | `cancelled` | The send was cancelled (e.g. stop-on-reply, opt-out, or manual cancel) before it went out. | Expected when a stop rule fired. | ## "It says Sent but my lead never got it" — why This is the most common confusion, and it usually is **not** a bug. `sent` means handed off to the channel, not confirmed on the device. The real reasons a `sent` message doesn't land: > [!NOTE] > > Often the message actually **did** arrive. On iOS 26+, Apple can screen messages from a sender the recipient hasn't saved and **suppress the delivery receipt** — so it shows `sent` even though it reached their inbox. Read receipts being off or a Focus mode do the same. Only `fallback` (not on iMessage) and `failed` signal a real problem. Genuine reasons a `sent` message doesn't land: 1. **The recipient isn't on iMessage** and you have no SMS fallback — the blue-bubble send has nowhere to land. See [Why didn't my contact get a message?](/troubleshooting/message-not-received) 2. **The line was restricted by Apple** and quietly stopped resolving new/cold recipients. See [Line health & Apple restrictions](/troubleshooting/line-health-and-restrictions). 3. **Wrong or stale number** — technically "sent" to a number the person no longer uses. 4. **The recipient blocked the number or has Do Not Disturb / focus filtering.** 5. **iMessage/carrier downgrade** — the message downgraded to SMS mid-flight. For provable delivery, rely on the `delivered` status (not `sent`), and check the conversation in the dashboard. ## Frequently asked questions > [accordion] Does 'sent' mean the person received my message? > > No. `sent` means Tuco handed the message to iMessage/SMS successfully. Receipt confirmation is the separate `delivered` status, shown where the channel supports it. > [accordion] My message is stuck in 'queued' — is something broken? > > Almost always no. `queued` means normal throttling — outside your send window/allowed days, waiting on line capacity, or a step delay. It sends automatically when conditions allow; limits never turn a message into `failed`. > [accordion] I got '201 scheduled' from the API — did my send fail? > > No — treat it as success. The line hit its daily limit, so Tuco deferred the send to the next window and returned a `scheduledDate`. It sends automatically; no retry needed. > [accordion] What's the difference between 'failed' and 'fallback'? > > `failed` means the message cannot be sent (invalid address / hard rejection / line problem). `fallback` means the primary channel (iMessage) isn't available for that recipient, so it should go out over your configured SMS/email fallback instead. > [card] [Why didn't my contact get a message?](/troubleshooting/message-not-received) > > Step-by-step checklist for a contact that wasn't messaged at all. # Use Cases Source: https://docs.tuco.ai/use-cases What teams use Tuco AI for: speed-to-lead, abandoned-checkout recovery, appointment reminders, follow-ups, reactivation and AI replies to opted-in contacts. **Tuco AI is for reaching the contacts you already have a relationship with — inbound leads, customers, and opt-in audiences — over iMessage, at the right moment.** Every use case below is built on **first-party, consented contacts** and **personalized, event-triggered** messages. Tuco is designed for warm outreach that respects consent, not for contacting people who haven't opted in. ## Speed-to-lead Text a new lead the instant they raise their hand — a form fill, a demo request, a reply — while intent is highest. * **Trigger:** new lead created / stage change in [HubSpot](/guides/send-imessage-from-hubspot) or [GoHighLevel](/guides/send-imessage-from-gohighlevel). * **Why iMessage:** a personal blue-bubble text gets a faster response than an email sitting in an inbox. ## Abandoned-checkout & cart recovery Bring back a shopper who started a purchase, using your own store's first-party customer data. * **Trigger:** an abandoned-checkout or cart event from your store/CRM. * **Personalized:** reference what they were buying and offer help — one-to-one, not a broadcast. ## Appointment reminders & no-show reduction Confirm, remind, and reschedule appointments so fewer slots go to waste. * **Trigger:** upcoming booking, or a status change. * **Two-way:** the recipient can reply to confirm or reschedule, and your workflow can [act on the reply](/integrations/ghl#check-for-replies-marketplace-workflow-action). ## Lead nurturing & follow-ups Send personalized follow-ups that stop when a lead replies. * **Built for it:** send each follow-up from a [GoHighLevel](/integrations/ghl) (or your CRM) workflow, and [check for replies](/integrations/ghl#check-for-replies-marketplace-workflow-action) before the next one. * **Consent-aware:** honor opt-outs on every step (see [compliance](/guides/imessage-compliance-tcpa)). ## Customer reactivation & win-back Re-engage dormant customers you already have a relationship with. * **Built for it:** the [reactivation](/features/reactivation) and [retroactive scanner](/features/retroactive-scanner) features find and follow up with quiet contacts. ## Conversational support & AI auto-replies Answer inbound questions instantly and hand the tricky ones to a human. * **Built for it:** the AI responder backed by your [knowledge base](/features/knowledge-base) drafts or sends replies; route the rest to a rep via [Telegram](/integrations/telegram-bot). ## Transactional & lifecycle updates Keep customers informed with the messages they expect from you. * Renewal and payment reminders, delivery and status updates, onboarding nudges — to your own customers. * Post-purchase review and referral requests, sent one-to-one after a real interaction. ## Agencies & client communication Run iMessage for multiple clients from one place, each with their own line and consented audience. * **Built for it:** agency/multi-workspace setup with per-line control and owner attribution. ## What Tuco is *not* for Tuco is for **warm, opt-in, personalized** outreach to your own contacts. It is not built for contacting people who never opted in, and Tuco enforces [per-line limits and anti-spam guidelines](/troubleshooting/line-health-and-restrictions) precisely so your lines stay healthy. ## Frequently asked questions > [accordion] Is Tuco right for abandoned-checkout recovery? > > Yes — recovering abandoned checkouts by messaging your own first-party customers is a core use case. The trigger fires from your store/CRM and each message is personalized to the shopper. > [accordion] Can I use Tuco for appointment reminders? > > Yes. Trigger reminders off upcoming bookings, and let recipients reply to confirm or reschedule — your workflow can branch on the reply. > [accordion] Who should I be messaging with Tuco? > > Contacts who have a relationship with you and have opted in — inbound leads, customers, and consented audiences. Always honor opt-outs. > [accordion] How do I make sends feel personal at volume? > > Trigger messages off events (a new lead, a reply, a stage change) and personalize with merge fields, so each contact gets an individual message rather than a broadcast. > [card] [Automate iMessage outreach](/guides/automate-imessage-sales-outreach) > > Set up triggered, personalized iMessage from your CRM. > [card] [Send from HubSpot / GoHighLevel](/guides/send-imessage-from-gohighlevel) > > Trigger an iMessage from any workflow. # What Your Leads See Source: https://docs.tuco.ai/what-leads-see Until a lead saves you, Apple shows “Maybe: your name” with Delete and Report Spam on every iMessage. See it, and the rules that keep you from being reported. **Until a lead saves your contact or taps Mark as Known, Apple shows them “Maybe: your name” and a spam warning with Delete on every message — not just the first.** It used to disappear after one message. Now it stays, so every message you send is a chance to be reported. ![Preview of Apple's unknown-sender screens: Maybe: Your Name, the spam warning with Delete and Mark as Known, and the Delete and Report Spam sheet](https://mintcdn.com/tucoai/be1Wk8zTclBS1V7p/images/what-leads-see.png?fit=max\&auto=format\&n=be1Wk8zTclBS1V7p\&q=85\&s=702a0c8476c08710c95371e370a6108f) Preview — your line's display name appears after “Maybe:”. Left: Messages on Mac. Right: tapping Delete on iPhone. Every line order returns a `recipientPreviewUrl` — a hosted version of this preview under your line's own display name. See [Create Line Request](/api-reference/endpoint/create-line-request). ## What one tap does Tapping **Delete** opens Apple's sheet: *“Report this conversation as spam by sending it to your network provider and Apple from your phone number.”* One more tap — **Delete and Report Spam** — sends the report. A few reports can ban a line permanently, even when the person opted in. See [line health](/troubleshooting/line-health-and-restrictions). ## The rules > [card] Do > > * Message people who opted in recently and will recognise your name. > * Write like a person — short, specific, conversational. > * Re-engaging older leads (under a month)? A **different, personal message for each one**, and **3–5 minutes between leads**. > * Ask them to save your contact once they reply — that removes the warning for good. > [card] Don't > > * Message anyone who opted in **more than a month ago** and may no longer remember your brand. > * Send the **same templated message** to a batch of old leads. > * Use **high-pressure** sales tactics, chase people who went quiet, or reply rudely. > * Send **more than 4 follow-ups** to someone who hasn't replied. Some providers block you after 5 unanswered messages — Tuco doesn't, so behave properly. > * Assume the warning goes away after your first message. You agree to these rules — alongside the rest of the [Anti-Spam & Messaging Rules](https://tuco.ai/anti-spam-policy) — every time you order a line. ## Calls work the same way A regular call from your line can show **“Potential spam”** until the person saves your number or taps “Mark as known” — so text first, then call. [The FaceTime Audio add-on or the Registered caller ID add-on](/limits#calling) avoid it.