> ## Documentation Index
> Fetch the complete documentation index at: https://docs.tuco.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Close CRM Integration

> Connect Close to Tuco AI: move a lead into a status and it gets texted, see every message in Close's own 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.</Note>

## 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.

`{first}` becomes the contact's first name, `{name}` their full name. If we don't
know it, both become "there" — never a raw `{first}` at a real person.

### 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.</Note>

### 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.</Warning>

### 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.</Warning>

### Sending on something other than a status

Sometimes "text them again" shouldn't mean moving the lead through your pipeline.
For that, Tuco also adds a **Tuco Campaign** lead field you can map the same way —
set it from an Update Lead step, and the message mapped to that value sends. The
lead's status never moves.

### 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 a Tuco campaign, 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.</Note>

**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.</Note>

## 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.</Note>

### 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.

## 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.</Warning>

## 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.</Note>

### Accounts over 10,000 contacts

Close limits how far an app can page through contacts — Tuco can import about **10,000** in one pass.

If you have more than that, the first sync brings in a portion and the 15-minute sync keeps up with anything that **changes** in Close from then on. Contacts beyond the limit that are never edited won't arrive on their own. The Close card tells you when this has happened.

If your account is larger than 10,000 contacts, contact [support@tuco.ai](mailto:support@tuco.ai) and we'll run a full export-based import 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 four things. Disconnecting removes them.

| Item                         | Purpose                                                               |
| ---------------------------- | --------------------------------------------------------------------- |
| **Tuco Campaign** lead field | Optional second trigger, for sending without moving the lead's status |
| **Tuco Status** lead field   | Where Tuco writes back what happened                                  |
| A webhook subscription       | How Tuco hears about the field being set                              |
| 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.</Note>

## 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

<AccordionGroup>
  <Accordion title="A lead isn't sending">
    Check the **Tuco Status** field on the lead — it usually says why. The common causes are a campaign name that doesn't match, and no contact on the lead having a phone number.

    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>

  <Accordion title="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>

  <Accordion title="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>

  <Accordion title="Sequences stopped starting">
    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>

  <Accordion title="Not all my contacts imported">
    See [Accounts over 10,000 contacts](#accounts-over-10-000-contacts).
  </Accordion>
</AccordionGroup>