{"openapi":"3.1.0","info":{"title":"Callbell (BYOK) API","version":"0.1.0","description":"Callbell (BYOK) lets an AI assistant read your own Callbell data through the Callbell API with a key you supply (Callbell API key). Read-only: 12 tools (get_account_user, get_plan, list_channels, get_channel, list_contacts, get_contact_by_phone, list_contact_messages, list_teams, list_team_members, list_templates, list_funnels, list_custom_statuses). The BYOK key travels with each request, is...\n\nEvery operation is read-only or compute-only. The same tools are available over MCP (streamable HTTP) at https://byok-callbell.connectorbay.com/mcp.","contact":{"name":"Unify Dynamics LLC","email":"agent@connectorbay.com","url":"https://connectorbay.com/byok-callbell/docs"},"termsOfService":"https://connectorbay.com/byok-callbell/terms"},"servers":[{"url":"https://byok-callbell.connectorbay.com"}],"externalDocs":{"url":"https://connectorbay.com/byok-callbell/docs"},"security":[{"upstreamKey":[]}],"components":{"securitySchemes":{"bearer":{"type":"http","scheme":"bearer","description":"Optional. A Pro API key raises rate limits; no credentials are required."},"upstreamKey":{"type":"apiKey","in":"header","name":"X-Upstream-Key","description":"Your own key for the service this connector wraps (bring your own key). Used for that one call only; never stored, logged or cached."}},"schemas":{"Error":{"type":"object","properties":{"ok":{"const":false},"error":{"type":"object"}}}}},"paths":{"/v1/tools/get_account_user":{"post":{"operationId":"get_account_user","summary":"Check that the key works and show the name and email of the account user it belongs to. Use for \"Whose Callbell account ","description":"Check that the key works and show the name and email of the account user it belongs to. Use for \"Whose Callbell account is this key connected to\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{},"title":"get_account_userArguments","type":"object"}}}},"responses":{"200":{"description":"Tool result. `ok: true` on success; `ok: false` with a structured `error` (provider_unavailable, upstream_error, bad_input) when the tool could not answer.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"422":{"description":"Arguments failed validation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (see Retry-After)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-read-only":true}},"/v1/tools/get_plan":{"post":{"operationId":"get_plan","summary":"Show the Callbell plan name, included channels, user licenses, active user count and teams. Use for \"What Callbell plan ","description":"Show the Callbell plan name, included channels, user licenses, active user count and teams. Use for \"What Callbell plan am I on and how many seats are used\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{},"title":"get_planArguments","type":"object"}}}},"responses":{"200":{"description":"Tool result. `ok: true` on success; `ok: false` with a structured `error` (provider_unavailable, upstream_error, bad_input) when the tool could not answer.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"422":{"description":"Arguments failed validation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (see Retry-After)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-read-only":true}},"/v1/tools/list_channels":{"post":{"operationId":"list_channels","summary":"List the account's channels (WhatsApp, Facebook, Instagram, Telegram) with title, type, main flag and whether it was dis","description":"List the account's channels (WhatsApp, Facebook, Instagram, Telegram) with title, type, main flag and whether it was discarded. Use for \"Which WhatsApp channels are active in Callbell\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"type":{"anyOf":[{"enum":["facebook","whatsapp","instagram","telegram"],"type":"string"},{"type":"null"}],"default":null,"description":"Only channels of this type.","title":"Type"},"active":{"anyOf":[{"type":"boolean"},{"type":"null"}],"default":null,"description":"True for active channels only, false for inactive ones.","title":"Active"},"page":{"anyOf":[{"maximum":500,"minimum":1,"type":"integer"},{"type":"null"}],"default":1,"description":"Page number, starting at 1.","title":"Page"}},"title":"list_channelsArguments","type":"object"}}}},"responses":{"200":{"description":"Tool result. `ok: true` on success; `ok: false` with a structured `error` (provider_unavailable, upstream_error, bad_input) when the tool could not answer.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"422":{"description":"Arguments failed validation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (see Retry-After)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-read-only":true}},"/v1/tools/get_channel":{"post":{"operationId":"get_channel","summary":"Get one channel by its uuid: title, type and whether it is the main channel. Use for \"Show Callbell channel 7c996996fea9","description":"Get one channel by its uuid: title, type and whether it is the main channel. Use for \"Show Callbell channel 7c996996fea947f4a1d5a11e7fac84db\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"channel_uuid":{"description":"Channel uuid from list_channels.","maxLength":64,"title":"Channel Uuid","type":"string"}},"required":["channel_uuid"],"title":"get_channelArguments","type":"object"}}}},"responses":{"200":{"description":"Tool result. `ok: true` on success; `ok: false` with a structured `error` (provider_unavailable, upstream_error, bad_input) when the tool could not answer.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"422":{"description":"Arguments failed validation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (see Retry-After)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-read-only":true}},"/v1/tools/list_contacts":{"post":{"operationId":"list_contacts","summary":"List contacts, most recent conversation first, with name, phone number, source, tags, assigned user and custom fields. P","description":"List contacts, most recent conversation first, with name, phone number, source, tags, assigned user and custom fields. Pages stop at 500; use the cursor from meta.next to go further. Use for \"Which Callbell contacts are tagged 'lead'\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"tags":{"anyOf":[{"maxLength":200,"type":"string"},{"type":"null"}],"default":null,"description":"Comma-separated tags to match (case-insensitive), for example 'sales,lead'.","title":"Tags"},"source":{"anyOf":[{"maxLength":200,"type":"string"},{"type":"null"}],"default":null,"description":"Only contacts from this integration type, for example whatsapp.","title":"Source"},"team_uuid":{"anyOf":[{"maxLength":64,"type":"string"},{"type":"null"}],"default":null,"description":"Only contacts of this team uuid.","title":"Team Uuid"},"after":{"anyOf":[{"maxLength":500,"type":"string"},{"type":"null"}],"default":null,"description":"Cursor from meta.next of the previous answer; when given, page is ignored.","title":"After"},"page":{"anyOf":[{"maximum":500,"minimum":1,"type":"integer"},{"type":"null"}],"default":1,"description":"Page number, starting at 1 (maximum 500).","title":"Page"}},"title":"list_contactsArguments","type":"object"}}}},"responses":{"200":{"description":"Tool result. `ok: true` on success; `ok: false` with a structured `error` (provider_unavailable, upstream_error, bad_input) when the tool could not answer.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"422":{"description":"Arguments failed validation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (see Retry-After)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-read-only":true}},"/v1/tools/get_contact_by_phone":{"post":{"operationId":"get_contact_by_phone","summary":"Find one contact by phone number; searches the main WhatsApp channel unless a channel uuid is given. Use for \"Find the C","description":"Find one contact by phone number; searches the main WhatsApp channel unless a channel uuid is given. Use for \"Find the Callbell contact with phone +34600111222\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"phone_number":{"description":"Phone number of the contact in international format, for example +34600111222.","maxLength":30,"title":"Phone Number","type":"string"},"channel_uuid":{"anyOf":[{"maxLength":64,"type":"string"},{"type":"null"}],"default":null,"description":"Search on this channel uuid instead of the main WhatsApp channel.","title":"Channel Uuid"}},"required":["phone_number"],"title":"get_contact_by_phoneArguments","type":"object"}}}},"responses":{"200":{"description":"Tool result. `ok: true` on success; `ok: false` with a structured `error` (provider_unavailable, upstream_error, bad_input) when the tool could not answer.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"422":{"description":"Arguments failed validation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (see Retry-After)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-read-only":true}},"/v1/tools/list_contact_messages":{"post":{"operationId":"list_contact_messages","summary":"List the messages of one contact's conversation, newest first, with text, direction status (sent, received, note), chann","description":"List the messages of one contact's conversation, newest first, with text, direction status (sent, received, note), channel and numbers. Pages by cursor in meta.next. Use for \"What did contact 414a6d692bd645ed803f2e7ce360d4c8 write to us on Callbell\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"contact_uuid":{"description":"Contact uuid from list_contacts.","maxLength":64,"title":"Contact Uuid","type":"string"},"after":{"anyOf":[{"maxLength":500,"type":"string"},{"type":"null"}],"default":null,"description":"Cursor from meta.next of the previous answer; when given, page is ignored.","title":"After"},"page":{"anyOf":[{"maximum":500,"minimum":1,"type":"integer"},{"type":"null"}],"default":1,"description":"Page number, starting at 1.","title":"Page"}},"required":["contact_uuid"],"title":"list_contact_messagesArguments","type":"object"}}}},"responses":{"200":{"description":"Tool result. `ok: true` on success; `ok: false` with a structured `error` (provider_unavailable, upstream_error, bad_input) when the tool could not answer.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"422":{"description":"Arguments failed validation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (see Retry-After)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-read-only":true}},"/v1/tools/list_teams":{"post":{"operationId":"list_teams","summary":"List the account's teams with name, default flag and member count. Use for \"Which teams exist in Callbell\".","description":"List the account's teams with name, default flag and member count. Use for \"Which teams exist in Callbell\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"page":{"anyOf":[{"maximum":500,"minimum":1,"type":"integer"},{"type":"null"}],"default":1,"description":"Page number, starting at 1.","title":"Page"}},"title":"list_teamsArguments","type":"object"}}}},"responses":{"200":{"description":"Tool result. `ok: true` on success; `ok: false` with a structured `error` (provider_unavailable, upstream_error, bad_input) when the tool could not answer.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"422":{"description":"Arguments failed validation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (see Retry-After)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-read-only":true}},"/v1/tools/list_team_members":{"post":{"operationId":"list_team_members","summary":"List the members of one team with name, email, availability and custom status. Use for \"Who is available in the Callbell","description":"List the members of one team with name, email, availability and custom status. Use for \"Who is available in the Callbell Support team\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"team_uuid":{"description":"Team uuid from list_teams.","maxLength":64,"title":"Team Uuid","type":"string"},"status":{"anyOf":[{"enum":["available","away"],"type":"string"},{"type":"null"}],"default":null,"description":"Only members who are available or away.","title":"Status"},"page":{"anyOf":[{"maximum":500,"minimum":1,"type":"integer"},{"type":"null"}],"default":1,"description":"Page number, starting at 1.","title":"Page"}},"required":["team_uuid"],"title":"list_team_membersArguments","type":"object"}}}},"responses":{"200":{"description":"Tool result. `ok: true` on success; `ok: false` with a structured `error` (provider_unavailable, upstream_error, bad_input) when the tool could not answer.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"422":{"description":"Arguments failed validation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (see Retry-After)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-read-only":true}},"/v1/tools/list_templates":{"post":{"operationId":"list_templates","summary":"List WhatsApp message templates with title, type, category, approval status and text. Read only; nothing is sent. Use fo","description":"List WhatsApp message templates with title, type, category, approval status and text. Read only; nothing is sent. Use for \"Which Callbell templates are approved\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"page":{"anyOf":[{"maximum":500,"minimum":1,"type":"integer"},{"type":"null"}],"default":1,"description":"Page number, starting at 1.","title":"Page"}},"title":"list_templatesArguments","type":"object"}}}},"responses":{"200":{"description":"Tool result. `ok: true` on success; `ok: false` with a structured `error` (provider_unavailable, upstream_error, bad_input) when the tool could not answer.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"422":{"description":"Arguments failed validation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (see Retry-After)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-read-only":true}},"/v1/tools/list_funnels":{"post":{"operationId":"list_funnels","summary":"List the sales funnels (conversation stages) with position, name and emoji. Use for \"What funnel stages do we use in Cal","description":"List the sales funnels (conversation stages) with position, name and emoji. Use for \"What funnel stages do we use in Callbell\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{},"title":"list_funnelsArguments","type":"object"}}}},"responses":{"200":{"description":"Tool result. `ok: true` on success; `ok: false` with a structured `error` (provider_unavailable, upstream_error, bad_input) when the tool could not answer.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"422":{"description":"Arguments failed validation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (see Retry-After)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-read-only":true}},"/v1/tools/list_custom_statuses":{"post":{"operationId":"list_custom_statuses","summary":"List the custom availability statuses agents can set, such as 'In meeting'. Use for \"Which custom agent statuses exist i","description":"List the custom availability statuses agents can set, such as 'In meeting'. Use for \"Which custom agent statuses exist in Callbell\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"page":{"anyOf":[{"maximum":500,"minimum":1,"type":"integer"},{"type":"null"}],"default":1,"description":"Page number, starting at 1.","title":"Page"}},"title":"list_custom_statusesArguments","type":"object"}}}},"responses":{"200":{"description":"Tool result. `ok: true` on success; `ok: false` with a structured `error` (provider_unavailable, upstream_error, bad_input) when the tool could not answer.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"422":{"description":"Arguments failed validation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (see Retry-After)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-read-only":true}}}}