Upfirst

Подключение

Ничего устанавливать не нужно. Укажите вашему клиенту на https://mcp.upfirst.ai, и он проведет вас через вход в Upfirst при первом подключении. Авторизация — это стандартный вход через OAuth 2.1, поэтому никаких API-ключей копировать или хранить не нужно.

Сервер работает через потоковый HTTP и предоставляет вашему ассистенту 25 инструментов, которые могут как читать ваш аккаунт, так и изменять его. Выберите своего клиента ниже.

Upfirst есть в каталоге коннекторов Claude. Откройте claude.ai/directory/upfirst, добавьте Upfirst, затем войдите в Upfirst и подтвердите доступ. Это работает в десктопном приложении Claude и на claude.ai.

Добавьте его как пользовательский коннектор

1. Откройте Customize, затем Connectors.
2. Нажмите +, затем Add custom connector.
3. Назовите его Upfirst и вставьте URL ниже как URL удаленного MCP-сервера.
4. Оставьте поля расширенных Client ID и Client Secret пустыми.
5. Нажмите Add, затем Connect, войдите в Upfirst и подтвердите доступ.

https://mcp.upfirst.ai

На тарифах Team и Enterprise владелец добавляет коннектор один раз в настройках организации, а все остальные просто нажимают Connect.

Как бы вы ни подключались, первый вызов открывает страницу входа в Upfirst. Вы подтверждаете доступ один раз, и подключение остается привязанным к вашей организации с этого момента.

Соглашения

Несколько правил действуют для каждого инструмента. Каждый из них несет метку того, что он делает с вашими данными:

• Read Получает данные; никогда ничего не изменяет.
• Write Создает или обновляет запись.
• Delete Безвозвратно удаляет запись. Отмены нет.

Идентификаторы берутся из инструментов списков

Идентификаторы агентов берутся из list_agents, идентификаторы навыков — из list_agent_skills, идентификаторы знаний — из get_agent_knowledge, идентификаторы приветствий — из list_agent_greetings, идентификаторы пользовательских действий — из list_custom_actions, а идентификаторы звонков — из list_calls. Идентификаторы — это строки цифр. Инструменты навыков принимают идентификатор как skillId; инструменты знаний, приветствий и пользовательских действий принимают его как id. Инструментам обновления и удаления нужен только этот идентификатор. Они не принимают agentId.

Записи привязаны к агентам

Каждый навык, запись знаний и пользовательское действие привязаны к одному или нескольким агентам. Инструменты создания принимают agentIds — список с хотя бы одним идентификатором агента. Установите autoLinkNewAgents в true, чтобы также передавать запись каждому агенту, которого вы создадите позже. В этом случае agentIds должен перечислять всех текущих агентов. Инструменты обновления изменяют связи только тогда, когда вы отправляете и agentIds, и autoLinkNewAgents. Оставьте оба поля пустыми, чтобы сохранить связи как есть. Редактирование или удаление записи изменяет ее для каждого агента, к которому она привязана.

Постраничная навигация

get_agent_knowledge, list_calls и get_call_transcript принимают offset и limit и возвращают totalCount, поэтому страница всегда формируется из одного и того же отфильтрованного набора. Остальные инструменты списков возвращают все в одном ответе.

Часовые пояса

Простые даты (YYYY-MM-DD) читаются в часовом поясе бизнеса. Недельные расписания читаются в часовом поясе каждого агента, поэтому одна запись, привязанная к агентам в двух часовых поясах, следует местному времени для каждого. Передавайте полную дату и время в формате ISO 8601, когда вам нужен точный момент.

Удаление безвозвратно

Через это подключение восстановление невозможно. Удаленный навык, запись знаний или пользовательское действие исчезают у каждого агента, к которому они были привязаны, и эти агенты перестают их использовать в течение нескольких минут.

Некоторые настройки доступны только в панели управления

Голос, часовой пояс и язык; планирование навыков; OAuth-подключения, через которые проходит аутентификацию пользовательское действие; удаление навыка перевода; и импорт знаний с веб-сайта управляются в панели управления Upfirst, а не через MCP. Инструменты сообщают об этом там, где это применимо.

Примеры запросов

MCP-сервер Upfirst работает с любым совместимым AI-клиентом. Чтобы начать, скопируйте один из этих запросов в свой клиент и адаптируйте его под свой бизнес.

Найдите пробелы в знаниях вашего администратора

Вариант использования

Используйте этот сценарий, чтобы просмотреть звонки за прошедшую неделю и найти, где знаний администратора не хватило, чтобы вы знали, что добавить в его обучение.

Пример запроса

Вы помогаете находить пробелы в знаниях администратора Upfirst.

Просмотрите звонки за последние семь дней, затем прочитайте текущие знания администратора. Ищите вопросы, которые задавали звонящие и на которые он не мог хорошо ответить, информацию, которой ему не хватало, и повторяющиеся темы.

Для каждого пробела укажите на звонки, которые его демонстрируют, и предложите конкретную запись знаний, которая его заполнит, написанную так, как администратор должен отвечать. Сгруппируйте связанные пробелы вместе и ранжируйте их по частоте появления.

Ничего не меняйте. Представьте пробелы и предложенные записи для рассмотрения.

Администратор: [Name, or leave blank for all]

Настройте администратора по описанию

Вариант использования

Используйте этот сценарий, чтобы описать, как вы хотите, чтобы администратор обрабатывал звонки, и позвольте вашему ассистенту собрать настройку: приветствие, знания, правила перевода, расписания и навыки текстовых сообщений.

Пример запроса

Вы помогаете настроить AI-администратора Upfirst на основе простого описания того, как он должен обрабатывать звонки.

Превратите описание в полную настройку: приветствие и прощание, знания, необходимые для ответов на частые вопросы, правила перевода для звонков, которые должны достигать человека, расписания для информации или переводов, действующих только в определенные часы, и любые навыки текстовых сообщений, которые требует описание.

Спрашивайте о важных вещах, которые описание оставляет неясными, таких как часы работы, кому должны поступать звонки или как обрабатывать частые запросы, вместо того чтобы угадывать.

Покажите полное предлагаемое решение для рассмотрения перед созданием чего-либо, затем примените его после одобрения.

Как администратор должен обрабатывать звонки: [Describe your business, your hours, what callers usually need, and who calls should reach]

Исправьте звонок, который прошел неудачно

Вариант использования

Используйте этот сценарий, чтобы указать на звонок, который прошел не так, как вы хотели, сказать, что бы вы предпочли, и позволить вашему ассистенту скорректировать знания администратора, чтобы похожие звонки проходили лучше.

Пример запроса

Вы помогаете улучшить администратора Upfirst на основе звонка, который прошел неудачно.

Прочитайте звонок, на который я указываю, включая его транскрипт, и сравните, что сделал администратор, с тем, что я хотел, чтобы произошло. Выясните, что привело к такому результату: было ли что-то в его знаниях отсутствующим, неясным или противоречащим другой записи.

Предложите конкретные изменения, которые сделают такой звонок лучше в следующий раз, написанные как точные знания для добавления или редактирования, и объясните, чем каждое из них помогает.

Покажите изменения для рассмотрения перед применением, затем внесите одобренные правки.

Звонок: [ID or a short description of the call]
Что я хотел, чтобы произошло вместо этого: [Describe the outcome you were hoping for]

01

Аккаунт и агенты

Ориентируйтесь, затем читайте или обновляйте отдельного AI-администратора.

Начните здесь. Компактный снимок всего аккаунта: название бизнеса, каждый администратор с его часовым поясом, приветствием, номерами телефонов, навыками и знаниями, а также количество звонков, обработанных за последние 30 дней.

Без параметров.

Возвращает Название бизнеса · агенты (id, имя, часовой пояс, приветствие, номера телефонов, названия навыков и знаний) · звонки за последние 30 дней (только завершенные звонки; тестовые и архивные звонки не учитываются).

Перечислите AI-агентов организации. Используйте возвращенный id с инструментами, ограниченными агентом, ниже.

Без параметров.

Возвращает агентов, каждый с id и именем.

Прочитайте полные настройки разговора одного агента и привязанные номера телефонов.

Параметр	Тип	Описание
agentId	string обяз	Числовой id агента из list_agents.

Возвращает приветствие и прощание, тон голоса, скорость речи, музыку ожидания, часовой пояс, блокировку спама и бесплатных номеров, а также привязанные номера телефонов.

Измените настройки разговора агента. Частичное обновление: отправляйте только то, что меняется; требуется хотя бы одно изменяемое поле.

Параметр	Тип	Описание
agentId	string обяз	Агент для обновления.
greetingMessage	string необяз	Приветственное сообщение.
goodbyeMessage	string необяз	Прощальное сообщение.
voiceTone	enum необяз	friendly · professional
speechRate	number необяз	0.7 · 0.85 · 1 · 1.1 · 1.2
holdMusic	enum необяз	ringTone · gentleGuitar · marimba · softKeys
isSpamCallsBlocked	boolean необяз	Блокировать подозрительные спам-звонки.
isTollFreeCallsBlocked	boolean необяз	Блокировать звонки на бесплатные номера.

Голос, часовой пояс и язык управляются в панели управления и не могут быть изменены здесь. Два флага блокировки действуют на всю организацию: установка любого из них изменяет его для каждого активного агента, так же как в панели управления. greetingMessage — это приветствие по умолчанию. Приветствия для определенных часов или дат имеют свои инструменты в разделе Запланированные приветствия.

Возвращает обновленного агента в той же форме, что и get_agent_by_id.

02

Запланированные приветствия

Запланированное приветствие — это то, что администратор говорит первым на звонках, попадающих в его расписание, например приветствие после часов работы или праздничное приветствие. Каждое принадлежит одному агенту. Когда ни одно запланированное приветствие не соответствует времени звонка, агент использует свое приветствие по умолчанию, которое читается с помощью get_agent_by_id и изменяется с помощью update_agent.

Перечислите запланированные приветствия агента, включая неактивные. Прочитайте это перед изменением приветствия, чтобы ничего не было перезаписано незаметно.

Параметр	Тип	Описание
agentId	string обяз	Агент, чьи приветствия нужно перечислить.

Возвращает id каждого приветствия, text, флаг активности, kind и schedule. kind доступен только для чтения: text означает, что приветствие произносится как написано, instruction означает, что агент строит приветствие из него, а unknown означает, что оно еще не классифицировано.

Добавьте запланированное приветствие агенту. Приветствие сохраняется только тогда, когда весь запрос действителен.

Параметр	Тип	Описание
agentId	string обяз	Агент, которому принадлежит приветствие.
text	string обяз	Точные слова для произнесения или инструкция о том, как приветствовать.
schedule	object обяз	Когда приветствие используется, в часовом поясе агента. См. Расписания приветствий.
isActive	boolean необяз	Используется ли приветствие на звонках с самого начала. По умолчанию true.

Расписание не должно пересекаться с другим активным приветствием того же агента. Недельные часы и даты проверяются отдельно. kind устанавливается системой: он читает unknown сразу после записи и классифицируется в течение секунд.

Возвращает id нового приветствия и его поля.

Измените текст, флаг активности или расписание запланированного приветствия. Частичное обновление: отправляйте только то, что меняется; требуется хотя бы одно поле.

Параметр	Тип	Описание
id	string обяз	Id приветствия, из list_agent_greetings.
text	string необяз	Новый текст приветствия.
isActive	boolean необяз	Используется ли приветствие на звонках.
schedule	object необяз	Новое расписание. См. Расписания приветствий.

Новое расписание полностью заменяет сохраненное, поэтому сначала прочитайте приветствие и отправьте обратно полное расписание, которое вы хотите. Применяется то же правило пересечения, что и при создании. Изменение текста сбрасывает kind в unknown до повторной классификации.

Возвращает поля, которые записало обновление.

Безвозвратно удалите запланированное приветствие.

Параметр	Тип	Описание
id	string обяз	Id приветствия для удаления.

Восстановить удаленное приветствие невозможно. Звонки в его временном слоте затем используют другое подходящее приветствие или приветствие агента по умолчанию, если ни одно не подходит. Расписание приветствия содержит еженедельные часы в days и необязательные точные даты в dates, все в часовом поясе агента. days использует ту же структуру, что и Расписания: все семь дней, каждый с enabled и workingPeriods. Каждая запись в dates имеет date как YYYY-MM-DD и как минимум один временной диапазон в periods. Запись с датой имеет приоритет над еженедельными часами для этого дня — так вы настраиваете праздничное приветствие.

{
  "days": {
    "monday":    { "enabled": true,  "workingPeriods": [{ "from": "17:00", "to": "23:59" }] },
    "tuesday":   { "enabled": true,  "workingPeriods": [{ "from": "17:00", "to": "23:59" }] },
    "wednesday": { "enabled": true,  "workingPeriods": [{ "from": "17:00", "to": "23:59" }] },
    "thursday":  { "enabled": true,  "workingPeriods": [{ "from": "17:00", "to": "23:59" }] },
    "friday":    { "enabled": true,  "workingPeriods": [{ "from": "17:00", "to": "23:59" }] },
    "saturday":  { "enabled": false, "workingPeriods": [] },
    "sunday":    { "enabled": false, "workingPeriods": [] }
  },
  "dates": [
    { "date": "2026-12-25", "periods": [{ "from": "00:00", "to": "23:59" }] }
  ]
}

03

Навыки

Навык — это действие, которое администратор может выполнить во время звонка: отправить текстовое сообщение звонящему, отправить ссылку для записи, перевести звонок, забронировать встречу или вызвать внешний API. У каждого вида есть свои инструменты, поэтому передаваемые поля всегда соответствуют этому виду. Навыки записи здесь доступны только для чтения и управляются на панели управления. Настройки вебхук-навыка хранятся в пользовательском действии, с которым он связан; читайте и редактируйте их с помощью инструментов Пользовательские действия ниже.

Перечислите навыки, настроенные для агента, включая неактивные по умолчанию.

Параметр	Тип	Описание
agentId	string req	Агент, чьи навыки нужно перечислить.
llmTool	enum opt	Только навыки этого вида: sendSms · sendScheduleSms · transferCall · scheduleSlot · customWebhook.
includeInactive	boolean opt	Включить отключенные навыки. По умолчанию true.

Возвращает навыки: id, имя, слаг, вид, флаг активности, сохраненную конфигурацию, необязательное еженедельное расписание. Строка customWebhook имеет пустую конфигурацию и вебхук-блок с URL связанного действия, HTTP-методом и таймингом; читайте полную конфигурацию с помощью list_custom_actions.

Расписание учитывается при звонках только для навыков перевода. Другие виды сохраняют его, но игнорируют.

Добавьте навык отправки текстового сообщения: SMS, которое администратор может отправить звонящему во время звонка. sendSms отправляет сообщение как есть. sendScheduleSms отправляет его вместе со ссылкой на запись организации.

Параметр	Тип	Описание
agentIds	string[] req	Агенты, которые получат навык, минимум один. Id из list_agents.
autoLinkNewAgents	boolean opt	Также дать навык каждому агенту, созданному позже. Когда true, agentIds должен перечислять всех текущих агентов. По умолчанию false.
llmTool	enum req	sendSms · sendScheduleSms
name	string req	Короткая метка, отображается на панели управления.
message	string req	Текст SMS, который отправляет агент, до 306 символов.
instruction	string req	Когда агент должен отправить его во время звонка.
isActive	boolean opt	Включен с самого начала. По умолчанию true.

Сообщение проходит фильтр контента, который отклоняет рекламные или иным образом ограниченные формулировки.

Возвращает id нового навыка и отправленные поля (llmTool, name, message, instruction, isActive). Прочитайте сохраненный навык с помощью list_agent_skills.

Измените навык отправки текстового сообщения. Частичное обновление: изменяются только отправленные поля. Отправьте хотя бы одно настраиваемое поле или новый набор агентов.

Параметр	Тип	Описание
skillId	string req	Id навыка из list_agent_skills.
llmTool	enum opt	Переключение между sendSms и sendScheduleSms.
name	string opt	Новая метка.
message	string opt	Новый текст SMS, до 306 символов.
instruction	string opt	Новые указания, когда отправлять.
isActive	boolean opt	Включить или выключить навык.
agentIds	string[] opt	Новый набор агентов, которые получат навык. Отправьте его вместе с autoLinkNewAgents, или оставьте оба пустыми, чтобы сохранить текущие связи.
autoLinkNewAgents	boolean opt	Также дать навык каждому агенту, созданному позже. Когда true, agentIds должен перечислять всех текущих агентов.

Возвращает поля, записанные обновлением.

Навсегда удалите навык отправки текстового сообщения у всех агентов, с которыми он связан. Эти агенты перестанут отправлять это сообщение.

Параметр	Тип	Описание
skillId	string req	Id навыка для удаления.

Невозможно восстановить удаленный навык. Чтобы вернуть его, нужно создать его заново с нуля.

Возвращает { id, note }, где note подтверждает удаление простым языком.

Добавьте навык перевода: правило, которое передает живой звонок человеку. condition сообщает агенту, когда переводить, preTransferMessage — что он говорит звонящему сначала, а destinations — номера, на которые он звонит по порядку.

Параметр	Тип	Описание
agentIds	string[] req	Агенты, которые получат навык, минимум один. Id из list_agents.
autoLinkNewAgents	boolean opt	Также дать навык каждому агенту, созданному позже. Когда true, agentIds должен перечислять всех текущих агентов. По умолчанию false.
name	string req	Короткая метка, отображается на панели управления.
condition	string req	Когда переводить, простым языком.
preTransferMessage	string req	Что агент говорит перед переводом.
destinations	array req	Одна или несколько целей, пробуются по порядку, каждая { phoneNumber, label, phoneExtension }. phoneNumber обязателен и должен быть в формате E.164 (например, +12025550123).
ringTimeoutSeconds	number opt	Время звонка на каждый номер, 5–60.
noAnswerAction	enum opt	endCall · returnToAgent
transferMethod	enum opt	cold передает звонящего напрямую · warm сначала информирует цель.
transferCallerId	enum opt	Номер, который видит цель: upfirstNumber · callerNumber.
recordingMode	enum opt	agentOnly останавливает запись при переводе · fullCall продолжает запись после него.
isActive	boolean opt	Включен с самого начала. По умолчанию true.
schedule	object opt	Еженедельные часы, когда навык доступен, в часовом поясе агента. Опустите для постоянной доступности. См. Расписания.

Каждая цель должна находиться в той же стране, что и один из номеров Upfirst связанных агентов. Если опущено, навык использует настройки панели управления по умолчанию при звонке: 30-секундный звонок, завершение звонка при отсутствии ответа, холодный перевод, номер Upfirst как идентификатор звонящего, и запись останавливается при переводе.

Возвращает id нового навыка и отправленные поля. Прочитайте сохраненный навык с помощью list_agent_skills.

Измените навык перевода. Частичное обновление: изменяются только отправленные поля. Отправьте хотя бы одно настраиваемое поле или новый набор агентов.

Параметр	Тип	Описание
skillId	string req	Id навыка из list_agent_skills.
destinations	array opt	Заменяет весь список. Отправьте каждый номер, который хотите сохранить.
schedule	object opt	Заменяет сохраненные часы. null очищает расписание, делая навык доступным круглосуточно.
Другие поля создания	opt	name, condition, preTransferMessage, ringTimeoutSeconds, noAnswerAction, transferMethod, transferCallerId, recordingMode, isActive. Те же значения, что и при создании.
agentIds	string[] opt	Новый набор агентов, которые получат навык. Отправьте его вместе с autoLinkNewAgents, или оставьте оба пустыми, чтобы сохранить текущие связи.
autoLinkNewAgents	boolean opt	Также дать навык каждому агенту, созданному позже. Когда true, agentIds должен перечислять всех текущих агентов.

Каждая цель должна находиться в той же стране, что и один из номеров Upfirst связанных агентов.

Вид навыка фиксируется при создании. Передача id навыка записи или вебхук-навыка читается как «не найдено».

Возвращает поля, записанные обновлением.

Для этого нет инструмента. Навыки перевода удаляются на панели управления Upfirst. Через MCP вы можете вместо этого отключить его: установите isActive: false с помощью update_transfer_call_skill, и агент перестанет предлагать перевод, пока навык остается настроенным.

04

Знания

Знания администратора — это то, из чего он отвечает звонящим. На панели управления Upfirst эти записи находятся в разделе «Обучение». Каждая из них — это текст, который вы пишете, или контент, импортированный с веб-сайта. Запись может быть связана с несколькими агентами, и ее редактирование или удаление меняет ответы всех связанных агентов. Записи автоматически переобучают администратора в течение нескольких минут.

Прочитайте базу знаний агента. Каждая запись возвращается целиком с полным содержимым, никогда не в виде предпросмотра.

Параметр	Тип	Описание
agentId	string req	Агент, чьи знания нужно прочитать.
id	string opt	Вернуть только эту одну запись.
offset	number opt	Записи для пропуска. По умолчанию 0.
limit	number opt	Максимум записей, 1–100. По умолчанию 25.

Возвращает записи: id, имя, тип (текст/веб-сайт), флаг активности, полное содержимое, исходный URL и еженедельное расписание, а также totalCount.

Добавьте текстовую запись в обучение одного или нескольких администраторов. Новая запись попадает в начало списка каждого связанного агента.

Параметр	Тип	Описание
agentIds	string[] req	Агенты, которые получат запись, минимум один. Id из list_agents.
autoLinkNewAgents	boolean opt	Также дать запись каждому агенту, созданному позже. Когда true, agentIds должен перечислять всех текущих агентов. По умолчанию false.
name	string req	Отображаемое имя записи.
content	string req	Простой текст, до 250 000 символов.
isActive	boolean opt	Активна с самого начала. По умолчанию true.
schedule	object opt	Ограничить запись рабочими часами. Опустите для постоянной активности. См. Расписания.

Возвращает id новой записи, name, isActive, schedule (null при постоянной активности) и contentLength в символах. Прочитайте полную запись с помощью get_agent_knowledge.

Измените имя записи, флаг активности, содержимое, расписание или агентов, которые ее видят. Частичное обновление: отправьте хотя бы одно настраиваемое поле или новый набор агентов.

Параметр	Тип	Описание
id	string req	Id записи из get_agent_knowledge.
name, isActive	opt	Новое имя / флаг активности.
content	string opt	Новый текст, полностью заменяющий сохраненное содержимое. До 250 000 символов.
schedule	object opt	Новое расписание. null очищает его, делая запись всегда доступной; опустите, чтобы сохранить текущее.
agentIds	string[] opt	Новый набор агентов, которые получат запись. Отправьте его вместе с autoLinkNewAgents, или оставьте оба пустыми, чтобы сохранить текущие связи.
autoLinkNewAgents	boolean opt	Также дать запись каждому агенту, созданному позже. Когда true, agentIds должен перечислять всех текущих агентов.

Содержимое заменяется, а не дополняется. Сначала прочитайте запись с помощью get_agent_knowledge и отправьте обратно полный текст, который вы хотите, включая все, что сохраняете. Изменение влияет на ответы всех агентов, связанных с записью.

Возвращает поля, записанные обновлением. Новое содержимое возвращается как contentLength, а не как полный текст.

Навсегда удалите запись знаний.

Параметр	Тип	Описание
id	string req	Id записи для удаления.

Невозможно восстановить удаленную запись. Удаление убирает ее у всех агентов, с которыми она связана.

Возвращает { id, note }, где note подтверждает удаление простым языком. Расписание ограничивает запись базы знаний (или навык передачи) рабочими часами с учетом часового пояса агента. Это объект для каждого дня недели. Каждое отправляемое расписание должно включать все семь дней; день, в который запись не должна применяться, — это enabled: false с пустым workingPeriods. Время указывается в 24-часовом формате HH:MM в часовом поясе агента.

Запланированная запись доступна в знаниях администратора только в течение своих окон. Вне них запись ведет себя так, как будто ее не существует, поэтому администратор никогда не отвечает на основе нее в неподходящее время.

Это делает расписания надежным способом обработки фактов, зависящих от времени. Чтобы сделать часы работы и закрытия безошибочными, добавьте одну запись, ограниченную вашими рабочими часами, с текстом «Мы сейчас открыты», и вторую, ограниченную часами закрытия, с текстом «Мы сейчас закрыты». Активна всегда только одна, поэтому администратор не сможет их перепутать.

{
  "days": {
    "monday":    { "enabled": true,  "workingPeriods": [{ "from": "09:00", "to": "17:00" }] },
    "tuesday":   { "enabled": true,  "workingPeriods": [{ "from": "09:00", "to": "17:00" }] },
    "wednesday": { "enabled": true,  "workingPeriods": [{ "from": "09:00", "to": "17:00" }] },
    "thursday":  { "enabled": true,  "workingPeriods": [{ "from": "09:00", "to": "17:00" }] },
    "friday":    { "enabled": true,  "workingPeriods": [{ "from": "09:00", "to": "17:00" }] },
    "saturday":  { "enabled": false, "workingPeriods": [] },
    "sunday":    { "enabled": false, "workingPeriods": [] }
  }
}

05

Пользовательские действия

Пользовательское действие — это вызов, который администратор совершает к внешнему HTTP API. timing определяет, когда оно запускается: before срабатывает до начала разговора и может использовать только системные переменные; during предлагается агенту во время звонка, который решает на основе описания, вызывать ли его; after срабатывает после завершения звонка — либо каждый раз, либо когда выполняется условие на простом языке.

Переменные подставляются в url, параметры запроса, заголовки и тело как {{name}}. Действие привязано к одному или нескольким агентам, и его редактирование или удаление меняет поведение всех связанных агентов. В list_agent_skills навык customWebhook представляет собой представление пользовательского действия на стороне агента. OAuth-подключения, через которые действие может проходить аутентификацию, настраиваются на панели управления Upfirst.

Каждое пользовательское действие, которое может использовать агент, со всей его конфигурацией. Прочтите это перед перезаписью действия, чтобы ничего не было перезаписано незаметно.

Параметр	Тип	Описание
agentId	string req	Агент, чьи действия нужно перечислить. Включаются все действия, связанные с этим агентом.
id	string opt	Вернуть только это одно действие.

Возвращает customActions, каждый с id, agentIds (все агенты, с которыми связано действие), autoLinkNewAgents, именем, описанием, таймингом, HTTP-методом, url, типом аутентификации и id OAuth-подключения, запасным сообщением, таймаутом, флагом активности, переменными, параметрами запроса, заголовками, разрешенными полями вывода, примерами значений, шаблоном тела и условием после-тайминга.

Заголовок, имя которого похоже на учетные данные (token, key, secret, authorization), возвращается как [redacted]; реальное значение никогда не считывается. Удаленные действия пропускаются.

Добавьте пользовательское действие и свяжите его с одним или несколькими агентами.

Параметр	Тип	Описание
agentIds	string[] req	Агенты, которые получают действие, минимум один. Id из list_agents.
autoLinkNewAgents	boolean opt	Также предоставить действие каждому агенту, созданному позже. Когда true, agentIds должен перечислять всех текущих агентов. По умолчанию false.
name	string req	Короткая метка, отображается на панели управления.
description	string req	Что делает действие, на простом языке. Тайминг before и during ставит его перед агентом, который решает по этому тексту, вызывать ли API. Тайминг after игнорирует его.
timing	enum req	before · during · after
httpMethod	enum req	GET · POST · PUT · PATCH · DELETE
url	string req	Конечная точка, на которую отправляется запрос. Может содержать заполнители {{variable}}.
authType	enum req	none отправляет запрос без аутентификации · bearer требует заголовок Authorization в headers · customHeaders аутентифицируется через предоставленные вами заголовки · oauth_connection получает токен из подключения и требует oauthConnectionId.
fallbackMessage	string req	Что агент говорит звонящему, когда запрос не удается или истекает по таймауту.
oauthConnectionId	string opt	Числовой id подключенного OAuth-подключения. Требуется для oauth_connection, отклоняется для всех других типов аутентификации. Возьмите его из list_custom_actions на действии, которое уже его использует.
variables	array opt	Значения, подставляемые в запрос, каждое { name, description, exampleValue, isSystem, required }. name и description обязательны, и имена должны быть уникальными. Системные переменные заполняются Upfirst из самого звонка; пользовательские собираются от звонящего. Действие с таймингом before может использовать только системные переменные. По умолчанию [].
queryParams	array opt	Параметры строки запроса, каждый { key, value }. Значения могут использовать заполнители. По умолчанию [].
headers	array opt	Заголовки запроса, каждый { key, value }. Bearer-аутентификация несет свой токен в заголовке Authorization здесь. Никогда не отправляйте заполнитель [redacted] обратно. По умолчанию [].
allowedOutputFields	string[] opt	Поля JSON-ответа, которые агент может читать. Пустое передает ответ без изменений. По умолчанию [].
bodyTemplate	string opt	Тело запроса, отправляемое как есть с подставленными заполнителями. Пустое — для отсутствия тела.
sampleValues	object opt	Значение для каждого имени переменной, используется при пробном запуске действия.
timeoutSeconds	integer opt	1–30. По умолчанию 10.
isActive	boolean opt	Включено с самого начала. По умолчанию true.
condition	string or null opt	Только для тайминга after. Правило на простом языке, проверяемое по завершенному звонку; null срабатывает после каждого звонка. Оставьте пустым для before и during.

Возвращает созданное действие с его новым id.

Измените пользовательское действие. Частичное обновление: изменяются только отправленные поля. Отправьте хотя бы одно устанавливаемое поле или новый набор агентов. Списки заменяются целиком, а не объединяются, поэтому сначала прочитайте действие с помощью list_custom_actions.

Параметр	Тип	Описание
id	string req	Id действия из list_custom_actions.
agentIds	string[] opt	Новый набор агентов, которые получают действие. Отправьте его вместе с autoLinkNewAgents, или оставьте оба пустыми, чтобы сохранить текущие связи.
autoLinkNewAgents	boolean opt	Также предоставить действие каждому агенту, созданному позже. Когда true, agentIds должен перечислять всех текущих агентов.
oauthConnectionId	string or null opt	null очищает его. Отправьте null в том же вызове, который переводит действие с типа аутентификации oauth_connection.
condition	string or null opt	null очищает его. Отправьте null в том же вызове, который переводит действие с тайминга after.
variables, queryParams, headers, allowedOutputFields	array opt	Каждый заменяет весь свой список. Отправьте каждую запись, которую хотите сохранить. Заголовок с заполнителем [redacted] отклоняется; отправьте реальное значение или оставьте этот заголовок пустым.
Другие поля создания	opt	name, description, timing, httpMethod, url, authType, bodyTemplate, sampleValues, fallbackMessage, timeoutSeconds, isActive. Те же значения, что и при создании.

Действие, связанное с несколькими агентами, редактируется для всех них.

Возвращает поля, которые записало обновление.

Навсегда удалите пользовательское действие. Каждый агент, связанный с ним, перестает вызывать этот API.

Параметр	Тип	Описание
id	string req	Id действия для удаления.

Восстановить удаленное действие невозможно. Вернуть его означает создать заново с нуля, и list_custom_actions возвращает его конфигурацию только пока оно существует.

Возвращает { id, note }, где note подтверждает удаление на простом языке.

06

Звонки

Читайте историю звонков бизнеса, детали одного звонка и его транскрипт. Появляются только завершенные звонки; звонок отображается вскоре после завершения.

Список и фильтрация истории звонков, сначала самые новые. Компактные строки без транскриптов и сводок (используйте инструменты ниже для них).

Параметр	Тип	Описание
statuses	enum[] opt	Фильтр по результату, каждый звонок имеет ровно один: test · blocked · spam · hungUp · completed.
query	string opt	Полнотекстовый поиск по сводкам звонков и транскриптам.
tags	string[] opt	Совпадение со звонками, несущими любой из этих тегов (по имени или id).
startDate	date opt	Голый YYYY-MM-DD = календарный день в часовом поясе бизнеса, или полная ISO-дата и время.
endDate	date opt	Как выше; включительно.
archived	boolean opt	Вернуть архивные звонки вместо активных. По умолчанию false.
offset, limit	number opt	Постраничный вывод. limit — 1–100, по умолчанию 25.

Возвращает строки звонков (звонящий, время, длительность, результат, теги, связанный контакт, количество витков транскрипта) плюс totalCount.

Полные детали одного звонка, все, кроме текста транскрипта и записи.

Параметр	Тип	Описание
callId	string req	Числовой id звонка из list_calls.

Возвращает время, результат, номера звонящего и администратора, сводку, написанную ИИ, захваченные поля данных, навыки, которые использовал агент (с указанием, когда каждый сработал), теги, комментарии вашей команды и количество витков транскрипта.

Текст разговора одного звонка в виде упорядоченных витков, каждый с отметкой смещения [mm:ss] и его говорящим.

Параметр	Тип	Описание
callId	string req	Числовой id звонка из list_calls.
offset, limit	number opt	Постраничный вывод по виткам. limit — 1–200, по умолчанию 100. Типичный звонок помещается в один ответ; листайте только когда примечание говорит, что осталось больше витков.

Говорящие: Агент (ИИ-администратор), Звонящий (человек, который позвонил) и Переведенный (человек, которому звонок был передан).

Возвращает витки (смещение, говорящий, текст) плюс totalCount.

Часто задаваемые вопросы

Как заставить Upfirst начать отвечать на мои звонки?

Мы даем вам номер телефона. Вы можете раздавать этот номер и просить людей звонить на него напрямую, но большинство бизнесов перенаправляют на него звонки с линии, которую уже используют.

Вы выбираете, сколько перенаправлять: каждый звонок, только пропущенные или, в зависимости от вашего телефона, оператора или VoIP-системы, только в определенные часы. Шаги различаются для каждого провайдера, поэтому смотрите Перенаправление всех звонков на Upfirst для вашего.

Нужен ли мне API-ключ?

Нет. Авторизация — это стандартный вход OAuth 2.1. Первый вызов открывает страницу входа Upfirst, вы одобряете доступ один раз, и ничего не нужно копировать, вставлять или хранить.

С какими ИИ-ассистентами я могу это использовать?

С любым клиентом, поддерживающим удаленные MCP-серверы через HTTP. В разделе Подключение есть настройка для Claude, ChatGPT, Claude Code, Cursor, VS Code и Codex. Для всего остального укажите https://mcp.upfirst.ai как потоковый HTTP-сервер, и он обработает вход при первом вызове.

К чему может получить доступ мой ассистент?

Только к организации, в которую вы вошли. Каждый инструмент ограничен этой организацией, и id из любой другой никогда не доступны. Внутри нее ассистент может читать звонки и транскрипты, изменять настройки администратора, навыки, знания и пользовательские действия, а также выбирать, к каким администраторам каждое из них применяется, поэтому относитесь к подключению так же, как ко входу на панель управления.

Почему звонок, который я только что принял, не отображается? Only finished calls appear, and a call shows up shortly after it ends. Calls in progress are not available until they hang up. If a call is still missing, check whether it was archived, since list_calls returns active calls unless you pass archived: true.

What can't I do over MCP?

Voice, timezone, and language; scheduling skills; OAuth connections for custom actions; deleting a transfer skill; and importing knowledge from a website are all managed in the Upfirst dashboard. Call recordings are not available over this connection either. The tools say so where it applies.