All pages

Docs

Connections

Letting the AI read and write Google Calendar, Microsoft 365 calendars, Google Sheets and kintone during a call, and sending a summary to Slack, Chatwork, LINE WORKS or Microsoft Teams after it: connecting per tenant or per environment, the embedded connect page, and using connections in an agent.

View as Markdown

With connections (connectors), the AI reads and writes another service during the call: it finds free slots and books them, or looks up earlier records by phone number and records what it heard. After the call, a summary can be posted to a chat. You don't need to build an API yourself.

To call your own or a third-party API, use the agent's tools. Custom connections to third-party APIs (URL and API key) have been replaced by tools: an unsigned tool (sign: false) with an API key calls a third-party API directly. Custom connections you already created keep working.

Available connectors#

Connector Name How to connect Actions the AI can use
google_calendar Google Calendar Sign in with a Google account find_free_slots, create_event, cancel_event, find_events_by_phone_or_name
m365_calendar Microsoft 365 calendar Sign in with a Microsoft 365 work account find_free_slots, create_event, cancel_event, find_events_by_phone_or_name
google_sheets Google Sheets Sign in with a Google account find_row_by_phone, append_row
kintone kintone Sign in with an OAuth client registered on the customer's cybozu.com find_record_by_phone, create_record, update_record
slack Slack Paste an Incoming Webhook URL created in the customer's workspace Notify after the call
chatwork Chatwork Paste the customer's API token Notify after the call
lineworks LINE WORKS Sign in with an app and bot created in the customer's Developer Console Notify after the call
teams Microsoft Teams Paste a Workflows webhook URL Notify after the call
http URL and API key POST /v1/connections The tools you configure (up to 10)

Connect sign-in connectors from Connections in the dashboard or the embedded connect page. GET /v1/connectors (MCP: list_connectors) lists the available connectors, their action descriptions, the tool names shown to the AI (such as sheets_append_row) and the inputs each one asks for before connecting.

voicast does not offer connections that let the AI in calls use a remote MCP server. Such a connection would call the server from every conversation in the environment with the token of whoever signed in when setting it up. To use what an MCP server offers during calls, call the service's API with tools (an unsigned tool with an API key can call a third-party API directly).

Coming soon#

HubSpot appears in the connector list (GET /v1/connectors) once it is ready. Until then, naming it in the agent's connectors returns 422.

Tenant and environment connections#

A preset connection can be held in two ways.

Kind When to use How to connect
Tenant connection Each business (tenant) uses its own calendar or ledger The business opens the embedded connect page and connects. Create the link with Create a connect page link in the tenant's edit dialog in the dashboard, or with POST /v1/tenants/{id}/connect-links
Environment connection Your whole service uses one calendar or ledger Connect from Connections in the dashboard's side menu

During a call, the tenant connection is used first. If the tenant has one (even one that needs signing in again), voicast does not fall back to the environment connection. List a tenant's connections with GET /v1/tenants/{id}/connections.

voicast encrypts and stores credentials (OAuth tokens, API keys). They never appear in API responses or reach the voice server.

Google Sheets#

Connecting#

  1. Press Connect on the Google Sheets card, in Connections in the dashboard (environment connection) or on the embedded connect page (tenant connection).
  2. Sign in with a Google account and allow access. Leave every item on the consent screen checked; unchecking one makes the connection fail.
  3. voicast creates a ledger spreadsheet, "AI 電話応対の台帳", in that Google Drive. Row 1 of its sheet "台帳" holds the headers (received at, phone number, name, request).
  4. In the settings that open next, choose the spreadsheet, the sheet and the phone, name, request and received-at columns, then save. The connection becomes active. Until you save, it is needs_setup and is not given to the AI.
  • The only Google scope is drive.file: voicast reads and writes only spreadsheets it created and cannot see other files in the Drive. To use your existing ledger, paste it into the spreadsheet voicast created.
  • Phone numbers are written as text (leading zeros are kept).
  • If you rename or delete the sheet, choose the sheet again in the settings. Until then the AI gets not_configured. It also gets not_configured if the phone column header is missing.
  • Through the API, get the choices with GET /v1/connections/{id}/options (narrow with ?spreadsheet= and ?sheet=) and save them in the config of PATCH /v1/connections/{id} (spreadsheet_id, spreadsheet_name, sheet, phone_column, name_column, note_column, date_column).

Actions#

Action Tool name shown to the AI What it does
find_row_by_phone sheets_find_row_by_phone Finds ledger rows by phone number (reads up to the first 2,000 rows, returns up to 5). In phone calls, omitting the number uses the caller's number
append_row sheets_append_row Adds a row with the time received, phone number, name and request. Always used after the caller confirms (this cannot be turned off)

How the AI uses them#

Once you add the actions to an agent, the AI uses them as follows even if the agent's persona says nothing about the ledger.

  • find_row_by_phone: after taking the phone number and reading it back, the AI looks it up in the ledger. If it finds an earlier record, it mentions the previous request briefly, and it only confirms a name that is already in the ledger instead of asking for it again.
  • append_row: when the AI has heard everything, it records the request. Before recording, voicast asks the caller with a fixed message ("Just to confirm, …, for …. Shall I take down this request?"), and after recording it says "Your request has been recorded." Then the conversation ends. The request column gets the request plus other details it heard (such as the preferred date and time), briefly.
  • The AI ends a conversation without recording only when the caller declines. Conversations that end after just answering a question, or that are transferred to staff, are not recorded. If recording fails, the AI apologizes and says staff will call back.
  • Recording in the ledger does not mean a booking or anything else is done, so the conversation still ends with the agent's closing.

Google Calendar#

Connecting#

  1. Press Connect, sign in with a Google account and allow access. Leave every item on the consent screen checked; unchecking one makes the connection fail.
  2. On the setup page that follows, choose the calendar to book into (only writable calendars are listed), the opening hours (up to 4 ranges per weekday), the booking length and the buffer, and save. The connection becomes active.
  3. With the API, get { calendars: { id, name, primary }[] } from GET /v1/connections/{id}/options and save config (calendar_id, calendar_name, hours, duration_minutes, buffer_minutes, title_template) with PATCH /v1/connections/{id}. hours looks like { "mon": [["09:00", "12:30"], ["14:00", "18:00"]], "sun": [] }.
  • The event title is title_template (default 「予約({name})」). The purpose goes only into the description. Attendees are not notified.
  • Public holidays are not considered; block closed days with an all-day event.

Actions#

Action Name shown to the AI What it does
find_free_slots gcal_find_free_slots Finds open slots within the opening hours (up to 14 days, up to 8 slots)
create_event gcal_create_event Creates the booking event. Needs the caller's confirmation
cancel_event gcal_cancel_event Cancels a booking event. Needs the caller's confirmation
find_events_by_phone_or_name gcal_find_events_by_phone_or_name Finds up to 5 upcoming bookings by phone number (stored on events it created) or name

The AI asks for the preferred day, finds free slots and offers them, and calls the booking action once it has the time and name. Before booking, voicast asks the caller with a fixed message ("Just to confirm, Monday, October 19 at 2 p.m., refrigerator repair, under the name Taro Yamada. Shall I go ahead and book it?"), and after booking it says "Your appointment is booked for Monday, October 19 at 2 p.m." Cancellations work the same way, reading out the time of the booking that was found. To change a booking, one confirmation ("Shall I move the appointment … from … to …?") covers booking the new time first and then cancelling the old one.

Microsoft 365 calendar#

Connecting#

  1. Press Connect, sign in with a Microsoft 365 work account and grant access. Personal Microsoft accounts (such as Outlook.com) can't be connected. Depending on the organization's settings, an administrator of the organization may need to approve the app.
  2. On the settings screen that opens next, choose the calendar to book into (only calendars you can write to are listed), the opening hours, the booking length and the buffer before and after, then save. The connection becomes active. The settings and the API (GET /v1/connections/{id}/options and config on PATCH /v1/connections/{id}) are the same as for Google Calendar.
  • Event titles, notes, attendee notifications and holidays work the same as in Google Calendar.
  • Disconnecting deletes the tokens voicast holds. Also remove voicast under Apps and services in the Microsoft account.

Actions#

Action Name shown to the AI What it does
find_free_slots m365_find_free_slots Finds open slots within the opening hours (up to 14 days, up to 8 slots)
create_event m365_create_event Creates the booking event. Needs the caller's confirmation
cancel_event m365_cancel_event Cancels a booking event. Needs the caller's confirmation
find_events_by_phone_or_name m365_find_events_by_phone_or_name Finds up to 5 upcoming bookings by phone number (stored on events voicast creates) or name

The AI uses them the same way as Google Calendar (how it offers free times and confirms bookings and cancellations).

kintone#

Connecting#

The kintone OAuth client is registered by an administrator of the customer's cybozu.com.

  1. In cybozu.com Common Administration, add an OAuth client under External Connections, with redirect endpoint https://app.voicast.jp/api/connectors/callback, and allow the users who will connect.
  2. Press Connect, enter the subdomain (the xxx of xxx.cybozu.com), client ID and client secret, then sign in to kintone and allow access.
  3. On the setup page, choose the app and the phone, name and purpose fields (text, link or multi-line text). With the API, use GET /v1/connections/{id}/options (?app= lists that app's fields) and PATCH with config (app_id, app_name, phone_field, name_field, note_field).

Actions#

Action Name shown to the AI What it does
find_record_by_phone kintone_find_record_by_phone Finds up to 5 records by phone number (with or without hyphens)
create_record kintone_create_record Creates a record with phone, name and purpose. Needs the caller's confirmation
update_record kintone_update_record Updates the name and purpose of a found record. Needs the caller's confirmation

Only the fields chosen in the setup are given to the AI.

Notifications after a call#

When a call ends, the result, summary, collected fields and a link to the dashboard are sent. In the agent, list the connector without actions, for example { "connector": "teams" }.

Notifications to Slack, Chatwork and Microsoft Teams are sent by voicast. Whether they arrived and how many attempts were made appear under "Webhook deliveries" in the call record, for example as "Notification to Slack" (API: the rows of GET /v1/calls/{id}/webhooks whose event_type is voicast.notify, with the connector in connector). Temporary failures are retried. If the destination stops accepting messages (webhook deleted, token revoked, removed from the room and so on), the connection becomes needs_reauth and the reason is in the connection's config.notify_error. Paste the URL or token again to restore it.

Slack#

  1. At api.slack.com/apps, choose "Create New App" → "From scratch" and create an app in the workspace to notify. The app belongs to your workspace; you don't install anyone else's app.
  2. Turn on "Incoming Webhooks" in the app, then click "Add New Webhook" and choose the channel to post to.
  3. In Connect, paste the webhook URL it shows (https://hooks.slack.com/services/…) and save (API: POST /v1/connections with { "connector": "slack", "secret": "<URL>" }). A test notification is sent once before saving. A URL that can't be reached returns 422 verify_failed.

Chatwork#

  1. In Chatwork, click your name at the top right → "Integrations" → "API Token" in the left menu, and show your API token. On every plan except Personal, an organization administrator must approve API use (Chatwork's request page).
  2. In Connect, paste the API token and save (API: POST /v1/connections with { "connector": "chatwork", "secret": "<API token>" }). Before saving, voicast checks the Chatwork account with the token. A wrong token returns 422 verify_failed.
  3. In the settings that open next, choose the room for notifications and save (view-only rooms are not listed; API: { rooms } from GET /v1/connections/{id}/options and room_id, room_name in config).
  • Notifications are posted to the room as the owner of the API token. To avoid posting as a person, create an account for notifications and issue its token.
  • If the token is regenerated or the account leaves the room, notifications stop (they are not retried). Paste a new token to resume with the same room.

LINE WORKS#

  1. Create an app in the customer's LINE WORKS Developer Console with Redirect URL https://app.voicast.jp/api/connectors/callback and OAuth scopes bot and user.read. Turn Refresh Token Rotation on in the token settings.
  2. Create a bot, add it to the tenant and make it available to the member who will receive notifications.
  3. Press Connect, enter the app's client ID and client secret and the bot ID, then sign in and allow access.
  4. On the setup page, choose the member to notify (user_id and user_name in config with the API).

Messages are kept within 2,000 characters.

Microsoft Teams#

  1. In Teams Workflows, create a "Post to a channel when a webhook request is received" flow and set who can trigger it to "Anyone".
  2. In Connect, paste the flow's URL and save (API: POST /v1/connections with { "connector": "teams", "secret": "<URL>" }). A test notification is sent once before saving.

URLs of the retired Office 365 connectors (Incoming Webhook) are not accepted.

Using connections in an agent#

List connections in the agent's connectors. In the dashboard, open the agent's Connections section, choose a connector and its actions.

json
"connectors": [
  { "connector": "google_calendar", "actions": ["find_free_slots", "find_events_by_phone_or_name"], "confirm": ["create_event", "cancel_event"] },
  { "connector": "google_sheets", "actions": ["find_row_by_phone", "append_row"] },
  { "connector": "teams" },
  { "connection": "con_…", "actions": ["find_customer"] }
]
Field Description
connector A preset name (such as google_calendar). The tenant connection is used, or the environment connection if the tenant has none
connection A specific connection ID (con_…). Use this for custom connections (URL and API key)
actions Names of the actions the AI may use (for custom connections, the name of the connection's tools). Omit it for notification-only connectors
confirm Extra actions that need the caller's confirmation. Names not in actions are added to actions when saved
  • For actions that change data (such as append_row) and tools set to "confirm before use" in a connection's settings, are used after the caller agrees to a confirmation message, and the result is told in a fixed message (for presets, this cannot be turned off for actions that change data). See Tools for the messages.
  • When the agent has such tools and the caller wants to book, change or cancel, the conversation does not end until the tool has been used. If the tool fails, voicast says "I'm sorry, your booking has not been confirmed yet. A staff member will get back to you." (for failures the caller can fix, such as a slot that was just taken, another time is offered).
  • If the last result of such a tool is a success (a booking or a cancellation), the conversation ends with a short thank-you instead of the agent's closing (voicast has already told the caller what was done). If the last result was a failure or the tool was not used, it ends with closing. Failures of read-only tools and ledger records (append_row) are not counted.
  • Within one conversation, such a tool is not called twice with the same arguments; the second call returns the first result.
  • The AI gets only the actions listed by name in actions. Actions or tools added later are not given to the AI until you list them.
  • "*" (all) is not accepted in actions (422 invalid_config). Settings saved earlier with "*" were migrated to the list of action names at the time of the migration.
  • Only actions of connections in the active state are given to the AI.
  • Each connector may appear once, and up to 10 entries are allowed. If a tool name shown to the AI (such as sheets_append_row or api1_find_customer) clashes with a name in tools, you get 422.

Embedded connect page#

A page where a business (tenant) connects its own calendar or ledger with its own account. It does not show the voicast name, so you can present it as part of your service.

In the dashboard, use Create a connect page link in the tenant's edit dialog. Through the API (MCP: create_connect_link):

bash
curl https://api.voicast.jp/v1/tenants/ten_…/connect-links \
  -H "Authorization: Bearer $VOICAST_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "connectors": ["google_sheets"], "frame_origin": "https://app.example.com" }'
json
{ "url": "https://app.voicast.jp/connect/vcl_…", "expires_at": 1790000900000 }
Input Description
connectors Connectors to show on the page (all available ones if omitted). Custom connections cannot be shown
frame_origin The origin (https) of the parent page that embeds it in an iframe. Not needed when opening it in a new tab
  • The link expires after 15 minutes. Create a new one on your server each time the business opens your settings page.
  • Choose the language by adding ?lang=ja or ?lang=en to url (otherwise the browser's language is used).
  • No sign-in is needed. The link's token gives access to that tenant's connections only.

Embedding#

html
<iframe src="https://app.voicast.jp/connect/vcl_…?lang=en" title="Connections" style="width: 100%; height: 720px; border: 0"></iframe>

Pressing Connect opens the provider's sign-in in a small separate window (most providers cannot show their sign-in inside an iframe). After signing in, the business finishes the setup (calendar, ledger and so on) on the same page. Until that setup is saved, the connection is needs_setup and is not given to the AI. Check the result with GET /v1/tenants/{id}/connections.

Custom connections#

Custom connections are environment connections, and you can add as many as you like to an environment. Passing tenant_id when creating one returns 422 invalid_request; route per tenant with the tenant's external_id sent with each request. Reference them in the agent as { "connection": "con_…", "actions": [...] }; their tool names get a per-connection prefix (api1_…, api2_…).

URL and API key (http)#

Call your own or a third-party REST API with a base URL and an API key.

bash
curl https://api.voicast.jp/v1/connections \
  -H "Authorization: Bearer $VOICAST_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "connector": "http", "secret": "<API key>", "input": { "base_url": "https://api.example.com", "header": "Authorization" } }'
  • With header: "Authorization" the key is sent as Bearer <key>; with any other header (such as X-API-Key) the key is sent as is.
  • A header name and an API key are required even for APIs that need no authentication. Enter a header the API ignores (for example, X-API-Key with any value).
  • Before saving, voicast only checks the form of the URL and the header name (it does not call the API).
  • The connection starts as needs_setup; save up to 10 tools with PATCH /v1/connections/{id} to make it usable.
json
{
  "config": {
    "tools": [
      {
        "name": "find_customer",
        "description": "Find a customer by phone number",
        "method": "GET",
        "path": "/customers/search",
        "params": [{ "name": "phone", "description": "Phone number (digits only)", "required": true }],
        "confirm": false
      }
    ]
  }
}
  • Tools with confirm: true can carry a confirmation message (confirm_message) and a completion message (done_message): up to 200 characters, {argument name} inserts the value (the same as in Tools).
  • Arguments are always strings: query parameters for GET, a JSON body for POST (up to 10). path must stay under the connected base URL.
  • Each request carries an idempotency-key derived from the call and the tool call.
  • JSON responses are passed to the AI as is; anything else is passed as text (long text is cut).
  • Error responses reach the AI as the following kinds, and the AI tells the caller, for example, that someone will check and call back.
API response error given to the AI
401, 403 unauthorized (check the API key)
404 not_found
Any other non-2xx (3xx, 429, 5xx…) upstream_error
No response within 3 seconds timeout
A required argument is missing invalid_arguments

Allowed URLs#

URLs called by connections must be https. Literal IP addresses, localhost, .local, .internal, dotless host names and URLs with a user name or password are rejected. Redirects (3xx) are not followed.

Connection status#

status Meaning
active Usable
needs_setup Connected, but setup (choosing the calendar, ledger or recipient, saving tools and so on) is not finished. Not given to the AI
needs_reauth For connectors you connect by signing in, the token expired; sign in again. For Slack, Chatwork and Microsoft Teams, the notification destination stopped accepting messages (reason in config.notify_error); paste the URL or token again

Connections do not expire just because there were no calls for a while: voicast refreshes the tokens of idle connections every day.

If the token can no longer be refreshed (access revoked in the provider's account, password changed and so on), the connection becomes needs_reauth and the connection.needs_reauth webhook is sent (once). For a tenant connection the payload includes tenant, so give that business a new connect page link and have them connect again.

Deleting a tenant disconnects its connections. Deleting a connection (DELETE /v1/connections/{id}) also revokes the provider's token (for Microsoft 365, kintone, Slack, Chatwork and Microsoft Teams, which have no revocation API, voicast deletes the token or URL it holds).