Участники и идентификаторы

GET /workspace/members и PUT/DELETE /workspace/members/{user_id}/identities — список участников workspace и привязка к ним ваших идентификаторов из CRM или телефонии.

Для интеграций, которые знают людей по своим id

CRM знает менеджера как пользователя 12345, АТС — как добавочный 101. Привяжите эти идентификаторы к участникам workspace один раз, и каждая загрузка сможет назвать автора как X-Author: external:amocrm:12345 — без таблицы соответствий на вашей стороне. См. Назначение автора.

Только владельцам

Эндпоинтам нужен ключ, созданный с опцией Разрешить управление участниками, а создать такой ключ может только владелец workspace: в списке есть email, а привязка идентификаторов решает, кто получит чьи звонки. Остальные ключи получают 403 members_scope_required. См. Аутентификация → Права ключа.

Те же идентификаторы владелец может настраивать в приложении: Настройки → Участники → Внешние идентификаторы рядом с каждым участником.

Список участников

GET /workspace/members — активные участники workspace ключа со всем, что к ним привязано. Пригодится, чтобы построить в настройках выбор «менеджер CRM → участник workspace» и видеть, что уже настроено.

curl https://app.memoai.tech/api/v1/developer/workspace/members \
  -H "Authorization: Bearer mk_live_your_key_here"

{
  "items": [
    {
      "id": "9c2d4e6f-1a2b-4c3d-8e9f-0a1b2c3d4e5f",
      "email": "ivanov@company.com",
      "name": "Иван Иванов",
      "role": "user",
      "identities": [
        { "provider": "amocrm", "external_id": "12345" },
        { "provider": "mango", "external_id": "ext-101" }
      ]
    }
  ],
  "total": 1
}

Поле	Тип	Описание
`items[].id`	UUID	Id участника — годится и как `X-Author: user:<id>`, и как `{user_id}` ниже.
`items[].email`	string	Email регистрации — годится и как `X-Author: email:<адрес>`.
`items[].name`	string \| null	Отображаемое имя.
`items[].role`	string	`owner` или `user`.
`items[].identities[]`	array	Привязанные идентификаторы как `{ provider, external_id }`. Пусто, если нет.

Возвращаются только активные участники, приглашения — нет. Список без пагинации (workspace небольшие), не больше 1000 участников.

Привязать идентификатор

PUT /workspace/members/{user_id}/identities — привязывает один идентификатор к участнику. Идемпотентно: повторная привязка той же пары возвращает 200 вместо 201.

curl -X PUT https://app.memoai.tech/api/v1/developer/workspace/members/9c2d4e6f-1a2b-4c3d-8e9f-0a1b2c3d4e5f/identities \
  -H "Authorization: Bearer mk_live_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{"provider": "amocrm", "external_id": "12345"}'

import httpx

resp = httpx.put(
    "https://app.memoai.tech/api/v1/developer/workspace/members/9c2d4e6f-1a2b-4c3d-8e9f-0a1b2c3d4e5f/identities",
    headers={"Authorization": "Bearer mk_live_your_key_here"},
    json={"provider": "amocrm", "external_id": "12345"},
)
resp.raise_for_status()   # 201 создано, 200 уже было

const res = await fetch(
  "https://app.memoai.tech/api/v1/developer/workspace/members/9c2d4e6f-1a2b-4c3d-8e9f-0a1b2c3d4e5f/identities",
  {
    method: "PUT",
    headers: {
      Authorization: "Bearer mk_live_your_key_here",
      "Content-Type": "application/json",
    },
    body: JSON.stringify({ provider: "amocrm", external_id: "12345" }),
  },
);
if (!res.ok) throw new Error(`HTTP ${res.status}`);

Поле	Правила
`provider`	Ваша метка внешней системы: 1–32 символа, `a-z`, `0-9`, `_`, `-`. При сохранении приводится к строчным. Фиксированного списка нет — `amocrm`, `bitrix24`, `hubspot`, `mango`, `uis` лишь соглашения.
`external_id`	Идентификатор человека в этой системе: 1–128 печатаемых ASCII-символов, сравнивается точно (регистр важен).

У одного участника может быть сколько угодно идентификаторов — id в CRM и два добавочных, например. Но одна пара provider + external_id указывает ровно на одного участника в workspace: привязка ее к другому вернет 409 identity_conflict, пока не отвяжете.

Ответ: 201 (создано) или 200 (уже было) с { "provider", "external_id" }.

Отвязать идентификатор

DELETE /workspace/members/{user_id}/identities/{provider}/{external_id} — 204 при успехе, 404, если ничего не было привязано. external_id с / или : кодируйте для URL.

curl -X DELETE https://app.memoai.tech/api/v1/developer/workspace/members/9c2d4e6f-1a2b-4c3d-8e9f-0a1b2c3d4e5f/identities/amocrm/12345 \
  -H "Authorization: Bearer mk_live_your_key_here"

Жизненный цикл

При исключении участника из workspace его идентификаторы удаляются вместе с ним. Загрузки с его именем после этого падают с 422 author_not_member — привяжите заново, когда он вернется.
Идентификаторы живут внутри workspace: тот же amocrm:12345 в другом workspace — другой человек.

Ошибки

Статус	Код	Когда
`403`	`members_scope_required`	У ключа нет права управления участниками.
`403`	`api_key_required`	Вызов с OAuth-токеном вместо API-ключа.
`404`	`member_not_found`	`user_id` не активный участник workspace ключа.
`404`	`identity_not_found`	Нечего отвязывать.
`409`	`identity_conflict`	Пара привязана к другому участнику.
`422`	`invalid_identity`	`provider` или `external_id` не проходят правила выше.