Guide
CRM and automations
Contacts and custom fields across networks, broadcasts, drip sequences, event-driven workflows and comment-to-DM automations.
Updated Oct 14, 2026
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 | contacts |
Every plan |
| Custom fields | Custom Fields | custom_fields |
Every plan |
| Broadcasts | Broadcasts | broadcasts |
broadcasts feature (Pro) |
| Sequences | Sequences | sequences |
automations feature (Pro) |
| Workflows | Workflows | workflows |
automations feature (Pro) |
| Comment automations | 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.
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/bulkimports up to 1,000 at once.POST /v1/contacts/{id}/tagsadds and removes tags;GET /v1/contacts/tagslists the tags in use.PUT /v1/contacts/{id}/fields/{slug}sets a custom field (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
POST /v1/broadcastswith the sendingaccount_id, aname, themessage(text with{{first_name}},{{fields.<slug>}}placeholders, attachments).- Choose recipients:
segment_filters(tags, excluded tags, custom fields) orPOST /v1/broadcasts/{id}/recipientswithcontact_idsorphones.POST /v1/broadcasts/audience-previewcounts a segment first. POST /v1/broadcasts/{id}/sendnow, or…/schedulewithscheduled_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, thenPOST /v1/sequences/{id}/activate. POST /v1/sequences/{id}/enrollwithcontact_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.
{
"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_mentionandlive_commenttriggers, follower gates and audience filters. post_idarms the automation when a scheduled Socialit post publishes. Links in buttons are tracked, andclick_tagtags the contact on click.GET /v1/comment-automations/{id}/logsshows 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.