# CRM and automations

> Contacts and custom fields across networks, broadcasts, drip sequences, event-driven workflows and comment-to-DM automations.

Everyone who writes to one of your accounts becomes a **contact**. Contacts feed **broadcasts** (one-off bulk sends), **sequences** (time-based drips), **workflows** (event-driven graphs) and **comment automations** (comment-to-DM). Everything belongs to a profile and is scoped like the rest of the API.

| Resource | Reference | MCP toolset | Plan |
|---|---|---|---|
| Contacts, tags, channels | [Contacts](/docs/api-reference/contacts/) | `contacts` | Every plan |
| Custom fields | [Custom Fields](/docs/api-reference/custom-fields/) | `custom_fields` | Every plan |
| Broadcasts | [Broadcasts](/docs/api-reference/broadcasts/) | `broadcasts` | `broadcasts` feature (Pro) |
| Sequences | [Sequences](/docs/api-reference/sequences/) | `sequences` | `automations` feature (Pro) |
| Workflows | [Workflows](/docs/api-reference/workflows/) | `workflows` | `automations` feature (Pro) |
| Comment automations | [Comment Automations](/docs/api-reference/comment-automations/) | `comment_automations` | `automations` feature (Pro) |

Channels can be `instagram`, `facebook`, `x`, `bluesky`, `reddit`, `discord`, `mastodon` and `tiktok`.

## Contacts

A contact has a name, email, company, tags, custom field values and **channels**: one identity per network (an Instagram user, a Messenger user), each with its own subscription state.

```bash
curl -X POST https://api.socialit.com/v1/contacts \
  -H "Authorization: Bearer $SOCIALIT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "name": "Jana Nováková", "email": "jana@example.com", "tags": ["vip"], "profile_id": "pro_8Lq2Vx7Bn4Mc1Zr8Tw3Ys6Hd0Kp" }'
```

- `POST /v1/contacts/bulk` imports up to 1,000 at once.
- `POST /v1/contacts/{id}/tags` adds and removes tags; `GET /v1/contacts/tags` lists the tags in use.
- `PUT /v1/contacts/{id}/fields/{slug}` sets a [custom field](/docs/api-reference/custom-fields/) (text, number, date, boolean, select).
- Channels: `GET|POST /v1/contacts/{id}/channels`, `PATCH …/channels/{channelId}` to opt a channel in or out.

Events: `contact.created`, `contact.updated`, `contact.deleted`, `contact.tag_added`, `contact.tag_removed`, `contact.field_changed`.

## Broadcasts

1. `POST /v1/broadcasts` with the sending `account_id`, a `name`, the `message` (text with `{{first_name}}`, `{{fields.<slug>}}` placeholders, attachments).
2. Choose recipients: `segment_filters` (tags, excluded tags, custom fields) or `POST /v1/broadcasts/{id}/recipients` with `contact_ids` or `phones`. `POST /v1/broadcasts/audience-preview` counts a segment first.
3. `POST /v1/broadcasts/{id}/send` now, or `…/schedule` with `scheduled_at`.

Each recipient follows its channel's rules: Messenger and Instagram need the 24-hour window or a `HUMAN_AGENT` tag, otherwise the recipient is `skipped` with `outside_messaging_window`. Sends are paced per channel (for example Facebook 300, Instagram 100 messages per minute), adjustable with `rate_limit_per_minute`. `GET /v1/broadcasts/{id}/recipients` shows delivery per recipient.

## Sequences

A sequence is an ordered list of steps on one account. Each step has a `delay_minutes`, a `message` and an optional `condition` on contact variables.

- Create with `steps`, then `POST /v1/sequences/{id}/activate`.
- `POST /v1/sequences/{id}/enroll` with `contact_ids` (up to 1,000); `DELETE …/enroll/{contactId}` takes one out.
- By default a reply or an unsubscribe ends the enrollment (`exit_on_reply`, `exit_on_unsubscribe`).

Events: `sequence.enrolled`, `sequence.step_sent`, `sequence.completed`, `sequence.exited`.

## Workflows

A workflow is a graph of `nodes` and `edges` with exactly one `trigger` node. Triggers include `inbound_message`, `keyword`, `comment`, `story_mention`, `reaction`, `contact_tag_added`, `contact_field_changed`, `schedule`, `manual` and `api_call`.

| Node | Does |
|---|---|
| `send_message`, `reply_to_comment`, `private_reply` | Send text, templates, media, buttons or quick replies |
| `wait_for_reply`, `delay` | Wait for the contact or for time |
| `condition`, `a_b_split` | Branch on variables (`contact.tags`, `contact.fields.<slug>`, `last_message`…) or randomly |
| `set_variable`, `add_tag`, `remove_tag`, `set_field` | Update the run or the contact |
| `http_request` | Call your API (HTTPS, response saved for later nodes) |
| `ai` | Generate a reply with Claude (`system_prompt`, `user_prompt_template`) |
| `assign_conversation`, `handoff` | Hand the conversation to a person |
| `enroll_sequence`, `end` | Chain into a sequence, or stop |

`GET /v1/workflows/node-types` returns the full catalog with config schemas. Edit the graph while the workflow is `draft` or `paused`; every change is a new version (`/versions`, `…/restore`). Start runs with `POST /v1/workflows/{id}/trigger` (API trigger, honours `Idempotency-Key`) or `…/executions` (test runs), and inspect them with `…/executions/{executionId}/events`.

Events: `workflow.triggered`, `workflow.completed`, `workflow.failed`.

## Comment automations

Comment-to-DM, ManyChat style: when someone comments a keyword on a post (or anywhere on the account), Socialit replies publicly and sends a DM.

```json
{
  "account_id": "sa_instagram…",
  "name": "Price list",
  "post_id": "pst_2LwQ9xKfT1mB7cRzV3nYp8aHsJd",
  "keywords": ["price", "cena"],
  "dm_message": "Hi {{first_name}}! Here is our price list.",
  "buttons": [{ "type": "url", "title": "Open", "url": "https://acme.example/prices" }],
  "comment_reply": "Sent you a DM 📩",
  "repeat_policy": { "mode": "once" }
}
```

- Instagram and Facebook get the public reply and the DM; TikTok, Threads, LinkedIn, YouTube, Bluesky and Reddit get the public reply only.
- Instagram adds `story_reply`, `story_mention` and `live_comment` triggers, follower gates and audience filters.
- `post_id` arms the automation when a scheduled Socialit post publishes. Links in buttons are tracked, and `click_tag` tags the contact on click.
- `GET /v1/comment-automations/{id}/logs` shows every trigger, kept 90 days.

A matching comment automation answers before any `comment` workflow, and messages sent by automations never trigger workflows.

## Support assistant

`POST /v1/support/runs` asks the Socialit support assistant a question (with optional `context` such as a `post_id` or `request_id`) and returns `202` with a run to poll at `GET /v1/support/runs/{id}`. Answers cite the docs they used.

---

Source: https://socialit.com/docs/crm-automations/
