Ръководства

Връзки

Вашият AI асистент (Claude, ChatGPT) и гласовият агент по време на обаждане могат да четат Google Календар и Apple Calendar и след Вашето одобрение да променят съществуващо събитие - а гласовият агент на собствения двигател на volai освен това може направо в обаждането да провери свободен час и веднага да запише срещата. При Apple запазвайте непрозрачните идентификатори и внимавайте с повтарящите се серии.

Какво може и какво не може

• Изброява свързаните календари и техните събития.
• Променя заглавието, началото или края на съществуващо събитие.
• Гласовият агент на собствения двигател на volai проверява в обаждането свободен час и веднага записва срещата.
• Намира свободни часове и създава среща и извън обаждане, през REST и MCP.

Не може

• Не изтрива никое събитие.
• Не търси свободни часове между повече участници.

Свързване на Google акаунт

Google акаунт свързвате в портала в раздела Връзки (в менюто на портала на английски - елементът „Integrations“). Щом акаунтът е свързан, същият API ключ вижда същото през REST и през MCP - не е нужно второ влизане.

Акаунтът може да се разкачи в портала или чрез REST DELETE /v1/integrations/{id}. REST разкачва интеграцията веднага и без допълнително поле за потвърждение, затова го извиквайте едва след изрично одобрение от потребителя. MCP няма инструмент за разкачване.

Apple Calendar

Свързва се с парола за конкретно приложение (не с обикновената парола към Apple акаунта) в портала в раздела Данни и интеграции. Свързването е възможно и чрез REST POST /v1/integrations с {provider: "apple-calendar", username, appPassword, calendarUrl?}; MCP не приема данни за вход и използва акаунта едва след свързването.

list_calendar_events и REST GET /v1/integrations/{id}/events поддържат Apple Calendar. Върнатия непрозрачен externalId подавайте непроменен като eventId към get_calendar_event и при промени; той не е iCalendar UID. Ред с recurring: true представлява цялата повтаряща се серия и промяната му променя основата на серията, а не едно отделно повторение; отделните изключения се запазват.

calendarId трябва да е един от адресите, върнати от list_calendars - всичко друго API отхвърля с грешка 400 calendar_invalid_calendar.

Часове по време на обаждане

Гласовият агент на собствения двигател на volai може направо по телефона да провери свободен час и веднага да запише срещата - не става дума за AI асистент в чат, а за обаждане, което води самият гласов агент. Включва се в редактора на агента в раздела Календар: избирате връзката, календара и правилата за наличност (прозорци по дни от седмицата, продължителност на срещата, интервал между часовете, минимално предизвестие, хоризонт на търсене).

• Работи само при агент на собствения гласов двигател на volai - при агент на ElevenLabs настройката се запазва и изчаква автоматичното превключване на двигателя.
• Агентът никога не казва какво е записано в календара - само дали даден час е свободен.
• Телефонът на търсещия се записва в събитието само когато агентът го знае; скрит номер означава събитие без телефон.
• Същото търсене на свободни часове и записване на среща е възможно и извън обаждане през REST (POST .../availability, POST .../events) и MCP (find_free_slots, create_calendar_event).

Fakturoid и ABRA Flexi

Тази страница обхваща само календарите. Fakturoid и ABRA Flexi се свързват на същото място (list_integrations/GET /v1/integrations, разделът Данни и интеграции в портала), но четенето на фактури и използването им в задачи за напомняне има собствено ръководство, Фактури.

Ред за агента

Промяната на събитие винаги е шест стъпки в този ред:

• 1. list_integrations - свързаните календари и техния integrationId.
• 2. list_calendars - календарите на дадената връзка и техния calendarId.
• 3. list_calendar_events, после get_calendar_event с върнатия externalId като eventId - зарежда събитието и актуалната му sourceRevision.
• 4. propose_calendar_update - подготвя предложение за промяна, засега нищо не записва.
• 5. Одобрение от потребителя - агентът показва първоначалните стойности и предложението и едва тогава продължава.
• 6. confirm_calendar_update с confirm: true - едва тази стъпка записва промяната в Google/Apple.

REST еквиваленти: GET /v1/integrations, GET /v1/integrations/{id}/calendars, GET /v1/integrations/{id}/events, GET /v1/integrations/{id}/events/{eventId}, после POST /v1/integrations/{id}/events/{eventId}/propose с {calendarId, sourceRevision, patch} и след одобрение PATCH /v1/integrations/{id}/events/{eventId} със същите стойности и confirm: true.

Грешки

• calendar_stale_revision - Междувременно събитието е променено другаде - заредете го отново (get_calendar_event) и оставете потребителя да одобри новото предложение.
• calendar_oauth_failed - Google отхвърли влизането - връзката трябва да се направи отново в портала.
• calendar_unauthorized - Връзката е спряла да е валидна (отнет достъп, изтекъл токен) - свържете акаунта отново.
• calendar_confirmation_required - Запис без confirm: true - потвърдете предложението едва след одобрение от потребителя.
• calendar_verification_failed - Записът е минал, но свежото зареждане назад не съвпада с изпратената промяна - проверете състоянието ръчно, не редактирайте отново на сляпо.

Пълната таблица с всички кодове ще намерите в раздела Календари в справочника за REST API и в грешките на MCP.

Сигурност

Токените за достъп до Google или Apple акаунт REST API и MCP никога не връщат и ние ги съхраняваме криптирани. Apple appPassword изпращайте през REST само когато потребителят вече го е запазил на сигурно място в променлива на средата или в посочен от него файл - никога не го искайте в разговора и не го повтаряйте обратно. Интеграцията се разкачва в портала или чрез REST DELETE /v1/integrations/{id} след изрично одобрение от потребителя; MCP не предлага разкачване.