Core concepts | ParsChat API

Pre-release v1, published 2026-09-14. This page commits to the shape of the API, not to a date. We will build exactly what is documented here. The shape can still change until 2026-10-14; after that, changes follow Versioning and stability.

The banner comes off one page at a time as each route goes live. While it is here, build against the contract and assume the route is not callable yet.

The one rule

A channel always belongs to a robot. There is no free-standing Instagram connection. Create the robot first, then attach the channel to it.

create robot  →  attach channel  →  receive events

This is enforced in the data model, not a convention we could relax. A channel cannot exist without a robot to own it.

Connecting a channel before creating a robot fails validation. It is the most common first-integration error.

The objects

Robot

A workspace holding conversations, automation rules and training data. rbt_…

Channel

A connected surface, such as an Instagram page. Belongs to exactly one robot. chn_…

Conversation

One thread with one end customer, on one channel. cnv_…

A robot holds at most one channel per type. One robot cannot have two Instagram pages. Give the second page its own robot.

Customer and end user are two different people

These two words appear throughout this documentation and they never mean the same thing.

	Who it is	What they do
Customer	A business you serve	Has a robot. Their operators answer conversations
End user	A person who messages that business	Sends the Instagram DM or Telegram message that starts a conversation

If you are a partner, your customers are the businesses on your platform. Their end users are the public. A conversation is always between an end user and a customer’s operators or AI.

One robot per customer

If you serve many customers, create one robot per customer. That is what keeps one customer’s conversations, automation rules and training data out of another’s.

End users need no such separation: they are identified inside a robot’s conversations, and the same person messaging two different customers produces two unrelated conversations.

`external_id` is your own identifier

Every robot can carry an external_id: your own customer id. We return it on every event, so you never need a lookup table between our ids and yours.

{ "name": "Rose Flower Shop", "external_id": "shop_10422" }

external_id is unique per partner, so yours cannot collide with another partner’s. Reusing one of your own returns 409.

Messages carry an external_id too, doing a different job: it is your idempotency key. Send a message with an external_id you have used before and we will not create a duplicate. See Webhook events.

Capacity

How many robots and channels you may have comes from your plan. If you need more, contact our sales team.

When capacity runs out you get 403 capacity_exhausted. details tells you where you stand: occupied is your enabled channels, requested is how many this call needs, and capacity is what your plan allows.

{
  "error": {
    "code": "capacity_exhausted",
    "message": "You have reached the maximum number of channels your plan allows.",
    "request_id": "req_8f2Kq9mR",
    "details": { "occupied": 10, "requested": 1, "capacity": 10 }
  }
}

Deleting a robot or channel frees capacity immediately. Disabling a channel frees it too — capacity counts enabled channels only, so a paused customer’s page keeps its history, rules and configuration without occupying a slot. See Enable and disable a channel.