Your Instagram contacts, in your own code

List contacts in a stable order, optionally only those with a tag or one exact person.

tag

Only contacts carrying this tag (exact name).

igsid

Contacts with this Instagram-scoped id — one per connected account, since the id is only unique within an account.

limit

1–100, default 25.

cursor

The nextCursor from the previous page.

{
  "data": [ { "id": "ck…", "username": "maya.jewels", "tags": ["vip"], "canMessage": true, … } ],
  "nextCursor": "ck…"   // null on the last page
}

One contact by id — the whole contact object.

{ "data": { "id": "ck…", "username": "maya.jewels", "customFields": { "city": "Austin" }, "canMessage": true, … } }

• The contact.created webhook hands you a contactId and nothing else; this is how you turn it into the record.

The conversation with one contact, newest first.

direction

in (from them) or out (from you, including automations and broadcasts).

limit

1–100, default 25.

cursor

The nextCursor from the previous page.

{
  "data": [
    {
      "id": "msg…", "direction": "out", "kind": "dm", "text": "Your order has shipped 📦",
      "attachments": [], "status": "sent", "error": null, "externalId": "mid.…",
      "automationId": null, "createdAt": "2026-09-24T15:02:11.000Z"
    }
  ],
  "nextCursor": null
}

• kind is dm, comment, comment_reply, story_reply or postback.
• status is sent, mock (a simulated account, so nothing left MuChat) or failed — a failed send keeps the reason in error.
• attachments lists the media on the message as { type, url }. The raw Instagram envelope is never returned.
• automationId is set when an automation sent the message.

Send one DM to a contact from your connected Instagram account — text, or a file by public link.

{ "text": "Your order has shipped 📦" }        // 1–1000 characters
{ "attachmentUrl": "https://cdn.you.com/receipt.pdf" }   // or one public https link

{ "data": { "id": "msg…", "status": "sent", "kind": "text", "externalId": "…", "createdAt": "2026-09-24T15:02:11.000Z" } }

• Send exactly one of text or attachmentUrl — both, or neither, is a 400.
• Instagram only lets a business message someone within 24 hours of that person's last message. Outside it you get a 409 whose body also carries lastInboundAt and windowExpiresAt, so you can tell a closed window from a broken request. Check canMessage on the contact first.
• MuChat stores no files: Instagram fetches attachmentUrl itself, so it has to be a public https link to an image, video, audio file or PDF (jpg, png, gif, mp4, mov, mp3, m4a, pdf…) — not Word, Excel or other documents. Links that only resolve on a private network are refused.
• Every send is written into the conversation, including a failed one, so /contacts/:id/messages matches what the inbox shows.
• Text sends are plain text; buttons, links and templates are sent by automations.

Add tags to a contact, or remove them.

{ "tags": ["vip", "wholesale"], "mode": "add" }   // mode: "add" (default) or "remove"

{ "data": { "id": "ck…", "tags": ["vip", "wholesale"], … } }

• 1–30 tags per request, each up to 60 characters.
• A contact keeps at most 30 tags; extra ones are dropped when adding.

Set or clear a contact’s custom fields.

{ "fields": { "city": "Austin", "plan": "Pro", "churn_reason": null } }

{ "data": { "id": "ck…", "customFields": { "city": "Austin", "plan": "Pro" }, … } }

• Merges: keys you don't send are left alone. null (or "") clears a key. 1–20 keys per request, values up to 500 characters.
• Only keys you have declared under Contacts → Fields are accepted — GET /fields lists them. An unknown key rejects the whole request with a 400 naming it, rather than half-applying the write.
• Numbers and booleans are stored as strings, the way the app stores them, so a value written here compares equal to one typed into MuChat in a segment rule.

The custom fields this account has declared — the keys you may write.

{ "data": [ { "key": "city", "name": "City", "type": "text", "createdAt": "…" } ] }

• type is text, number, date or boolean. It describes what the field is for; values are stored and returned as strings.
• Not paged — the list is small and hand-made.

The account’s tag list, alphabetically.

{ "data": [ { "name": "vip", "color": "#0e9f8e", "createdAt": "…" } ] }

• This is the curated list from Settings → Automation → Tags. A contact can still carry a tag that was never added to it (an import, or a new name from POST /contacts/:id/tags), so read contact.tags for what a contact actually has.
• Tags are addressed by name everywhere in the API, so no id is returned.

Your saved segments and the rules behind each one.

{
  "data": [
    { "id": "sg…", "name": "VIPs who went quiet", "match": "all",
      "rules": [ { "field": "tag", "op": "has", "value": "vip" }, { "field": "last_interaction", "op": "before", "value": 30 } ],
      "createdAt": "…" }
  ]
}

• Not paged.
• A segment is a live filter, not a stored list — the rules tell you what the next endpoint is about to return.

The contacts matching a segment right now.

limit

1–100, default 25.

cursor

The nextCursor from the previous page.

{ "data": [ { "id": "ck…", "username": "maya.jewels", … } ], "nextCursor": "ck…" }

• Evaluated on every call, so someone who stopped matching yesterday isn’t here today.

Your drip sequences, with how many steps and how many people have been enrolled.

limit

1–100, default 25.

cursor

The nextCursor from the previous page.

{
  "data": [
    { "id": "sq…", "name": "Welcome series", "status": "LIVE", "steps": 3, "enrolled": 412, "createdAt": "…" }
  ],
  "nextCursor": null
}

• Only a LIVE sequence sends anything.
• This is what resolves the sequenceId a conversion.recorded webhook carries.

One sequence.

{ "data": { "id": "sq…", "name": "Welcome series", "status": "LIVE", "steps": 3, "enrolled": 412, "createdAt": "…" } }

• 404 when it belongs to another workspace or has been deleted — the two are indistinguishable on purpose.

List your automations, most recently updated first.

status

DRAFT, LIVE or STOPPED.

limit

1–100, default 50.

{ "data": [ { "id": "ck…", "name": "Auto-DM links from comments", "status": "LIVE", "builder": "flow", "triggerType": "COMMENT", "triggerTypes": ["COMMENT", "DM_KEYWORD"], "publishedAt": "…", … } ] }

• This one is a plain list with no cursor — it returns at most limit automations and no nextCursor.
• triggerTypes is every trigger that can start it right now; triggerType is the first of them, and null when every trigger is switched off.

The runs of one automation, newest first.

contactId

Only runs for this contact.

status

Only runs in this state, e.g. completed or waiting_reply.

limit

1–100, default 25.

cursor

The nextCursor from the previous page.

{
  "data": [ { "id": "run…", "automationId": "ck…", "contactId": "ck…", "status": "completed", "createdAt": "…", "updatedAt": "…" } ],
  "nextCursor": null
}

• The rows behind the automation.run webhook: it gives you a runId, and this is where you look it up or check later whether it finished.
• Whatever a contact typed into an Ask step stays inside MuChat and is not returned here.

Run a live automation for one contact — when a purchase, a form or a booking elsewhere should start a conversation here.

contactId

Required. The contact to run it for.

idempotencyKey

Optional, up to 120 characters. Also accepted as the Idempotency-Key header. The same key for the same contact on the same automation is one run, however many times the request arrives — send one whenever you might retry. A key is scoped to its contact, so reusing one for a different person starts their run rather than being mistaken for a retry.

{ "data": { "runId": "run…", "duplicate": false } }

• 201 when it started, 200 with duplicate: true when that idempotency key already ran.
• 409 with a reason when it can't run right now: not_live, window_closed (Instagram only allows a message within 24 hours of their last one), paused (someone on your team took the conversation over), unsubscribed, or wrong_channel. The message says what to do.
• 404 when the automation or the contact isn't in your workspace — the two read the same on purpose.
• It runs through exactly the same path a keyword match does, so everything the automation does — its steps, its tags, its follow-ups — happens as if they had triggered it.

Record a conversion — a purchase, booking or sign-up — for one of your conversion events.

{ "key": "purchase", "contactId": "ck…", "value": 1999 }   // value in minor units: 1999 = $19.99

{ "data": { "id": "cv…", "eventKey": "purchase", "contactId": "ck…", "automationId": "ck…", "value": 1999, "currency": "USD", "source": "api", … } }   // 201

• key is the event’s key from Settings → Automation → Conversion events. An unknown key is a 404; an archived event is a 410.
• Identify the person with contactId, or igsid if you only know their Instagram-scoped id. Both are optional.
• value is a whole number of minor units in the event’s currency; leave it out to use the event’s default. Decimals and negatives are rejected.
• Pass automationId to credit an automation yourself. Otherwise the conversion is credited to the last automation run or sequence that touched the contact in the 7 days before.

List recorded conversions, newest first.

key

Only this conversion event.

contactId

Only this contact.

limit

1–100, default 25.

cursor

The nextCursor from the previous page.

{ "data": [ { "id": "cv…", "eventKey": "purchase", "value": 1999, "currency": "USD", … } ], "nextCursor": null }