Managing members
Keep a group in line with your records with one list.
An agent that is a group's admin can keep its members in line with your records. Send one list of everyone who should be in the group:
POST /v1/agent/groups/{group}/sync
{"members": ["+966501234567", "0559876543", "+971501112222"]}HAI compares it with the group: people on the list and on HAI who are missing are added; people in the group who are not on the list are removed. The answer comes at once with a decision for every number; the changes then happen in steps of 20 people, never in the middle of a conversation. Read the outcome with GET /v1/agent/runs/{run} or wait for sync.finished.
Safety
- An empty list is refused. It would remove everyone.
- A big removal waits. A list that would remove more than 50 people, or more than a tenth of the group, answers
409 confirm_neededwith the count. Check it, then send the same list with"confirm": true. - People who left on their own are not added back. They come back as
left_group. To add them anyway, send their numbers in"readd"too. - Nobody who blocked the agent, or lets only their contacts add them, is added. Nobody a group admin removed is added back.
- The group's creator is removed only after the group is handed to another person.
Add "test": true to see the decisions without changing anything; it also tells you needs_confirm.
Results
| Result | Meaning |
|---|---|
add / already_member | Added, or already there. |
not_on_hai | No HAI account uses that number. |
left_group | Left on their own; use readd to add them back. |
removed_by_admin | A group admin removed them; not added back. |
blocked_the_agent / only_contacts_can_add | Their own choice; not added. |
remove (list absent, with uid) | In the group but not on your list. |
daily_limit, group_full, needs_approval | A limit; see Limits. |
Numbers may be in international form, with 00, or national for the agent's country (Saudi Arabia by default).