Skip to content
Docs

Guide

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.

Terminal
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 (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.