{"openapi":"3.1.0","info":{"title":"Twilio Conversations (BYOK) API","version":"0.1.0","description":"Twilio Conversations (BYOK) lets an AI assistant read your own Twilio Conversations data through the Twilio Conversations API with a key you supply (Account SID or API key SID (use a restricted API key, SID starts with SK, rather than the main Auth Token where possible)). Read-only: 10 tools (get_global_configuration, list_services, list_conversations, get_conversation,...\n\nEvery operation is read-only or compute-only. The same tools are available over MCP (streamable HTTP) at https://byok-twilio-conversations.connectorbay.com/mcp.","contact":{"name":"Unify Dynamics LLC","email":"agent@connectorbay.com","url":"https://connectorbay.com/byok-twilio-conversations/docs"},"termsOfService":"https://connectorbay.com/byok-twilio-conversations/terms"},"servers":[{"url":"https://byok-twilio-conversations.connectorbay.com"}],"externalDocs":{"url":"https://connectorbay.com/byok-twilio-conversations/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_global_configuration":{"post":{"operationId":"get_global_configuration","summary":"Show the account-wide Conversations settings: default service, default messaging service and the default inactivity and ","description":"Show the account-wide Conversations settings: default service, default messaging service and the default inactivity and closing timers. Use for \"What are my default Twilio Conversations settings\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{},"title":"get_global_configurationArguments","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_services":{"post":{"operationId":"list_services","summary":"List the Conversations services of the account. Use for \"Which Twilio Conversations services do I have\".","description":"List the Conversations services of the account. Use for \"Which Twilio Conversations services do I have\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"page_size":{"anyOf":[{"maximum":1000,"minimum":1,"type":"integer"},{"type":"null"}],"default":50,"description":"How many results to return (1 to 1000).","title":"Page Size"},"page_token":{"anyOf":[{"maxLength":300,"type":"string"},{"type":"null"}],"default":null,"description":"Paging token: the PageToken value inside meta.next_page_url from the previous answer (leave empty for the first page).","title":"Page Token"}},"title":"list_servicesArguments","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_conversations":{"post":{"operationId":"list_conversations","summary":"List conversations in the default service with state and dates, optionally filtered by state and creation time. Message ","description":"List conversations in the default service with state and dates, optionally filtered by state and creation time. Message text is not returned. Use for \"Which Twilio conversations are currently active\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"state":{"anyOf":[{"enum":["initializing","inactive","active","closed"],"type":"string"},{"type":"null"}],"default":null,"description":"Only conversations in this state.","title":"State"},"start_date":{"anyOf":[{"maxLength":40,"type":"string"},{"type":"null"}],"default":null,"description":"Only conversations created on or after this ISO 8601 time, for example 2026-01-01T00:00:00Z.","title":"Start Date"},"end_date":{"anyOf":[{"maxLength":40,"type":"string"},{"type":"null"}],"default":null,"description":"Only conversations created on or before this ISO 8601 time.","title":"End Date"},"page_size":{"anyOf":[{"maximum":1000,"minimum":1,"type":"integer"},{"type":"null"}],"default":50,"description":"How many results to return (1 to 1000).","title":"Page Size"},"page_token":{"anyOf":[{"maxLength":300,"type":"string"},{"type":"null"}],"default":null,"description":"Paging token: the PageToken value inside meta.next_page_url from the previous answer (leave empty for the first page).","title":"Page Token"}},"title":"list_conversationsArguments","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_conversation":{"post":{"operationId":"get_conversation","summary":"Get one conversation from the default service: names, state, linked services and timestamps. Use for \"What is the state ","description":"Get one conversation from the default service: names, state, linked services and timestamps. Use for \"What is the state of Twilio conversation CHaaa\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"conversation_sid":{"description":"The conversation SID ('CH' + 32 hex characters) or its unique name.","maxLength":64,"title":"Conversation Sid","type":"string"}},"required":["conversation_sid"],"title":"get_conversationArguments","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_service_conversations":{"post":{"operationId":"list_service_conversations","summary":"List conversations of one specific Conversations service, optionally filtered by state and creation time. Use for \"Which","description":"List conversations of one specific Conversations service, optionally filtered by state and creation time. Use for \"Which closed conversations does my second Conversations service have\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"chat_service_sid":{"description":"The SID of the Conversations service: 'IS' followed by 32 hex characters.","maxLength":34,"title":"Chat Service Sid","type":"string"},"state":{"anyOf":[{"enum":["initializing","inactive","active","closed"],"type":"string"},{"type":"null"}],"default":null,"description":"Only conversations in this state.","title":"State"},"start_date":{"anyOf":[{"maxLength":40,"type":"string"},{"type":"null"}],"default":null,"description":"Only conversations created on or after this ISO 8601 time, for example 2026-01-01T00:00:00Z.","title":"Start Date"},"end_date":{"anyOf":[{"maxLength":40,"type":"string"},{"type":"null"}],"default":null,"description":"Only conversations created on or before this ISO 8601 time.","title":"End Date"},"page_size":{"anyOf":[{"maximum":1000,"minimum":1,"type":"integer"},{"type":"null"}],"default":50,"description":"How many results to return (1 to 1000).","title":"Page Size"},"page_token":{"anyOf":[{"maxLength":300,"type":"string"},{"type":"null"}],"default":null,"description":"Paging token: the PageToken value inside meta.next_page_url from the previous answer (leave empty for the first page).","title":"Page Token"}},"required":["chat_service_sid"],"title":"list_service_conversationsArguments","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_participants":{"post":{"operationId":"list_participants","summary":"List the participants of a conversation: identity, role and last-read position. Phone numbers and addresses of the parti","description":"List the participants of a conversation: identity, role and last-read position. Phone numbers and addresses of the participants are not returned. Use for \"Who takes part in Twilio conversation CHaaa\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"conversation_sid":{"description":"The SID of the conversation: 'CH' followed by 32 hex characters.","maxLength":34,"title":"Conversation Sid","type":"string"},"page_size":{"anyOf":[{"maximum":1000,"minimum":1,"type":"integer"},{"type":"null"}],"default":50,"description":"How many results to return (1 to 1000).","title":"Page Size"},"page_token":{"anyOf":[{"maxLength":300,"type":"string"},{"type":"null"}],"default":null,"description":"Paging token: the PageToken value inside meta.next_page_url from the previous answer (leave empty for the first page).","title":"Page Token"}},"required":["conversation_sid"],"title":"list_participantsArguments","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_roles":{"post":{"operationId":"list_roles","summary":"List the user roles of the default service with their type (conversation or service) and permission names. Use for \"What","description":"List the user roles of the default service with their type (conversation or service) and permission names. Use for \"What roles can Conversations users have\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"page_size":{"anyOf":[{"maximum":1000,"minimum":1,"type":"integer"},{"type":"null"}],"default":50,"description":"How many results to return (1 to 1000).","title":"Page Size"},"page_token":{"anyOf":[{"maxLength":300,"type":"string"},{"type":"null"}],"default":null,"description":"Paging token: the PageToken value inside meta.next_page_url from the previous answer (leave empty for the first page).","title":"Page Token"}},"title":"list_rolesArguments","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_conversation_webhooks":{"post":{"operationId":"list_conversation_webhooks","summary":"List the webhooks scoped to one conversation: target type and URL. Use for \"Which webhooks fire for Twilio conversation ","description":"List the webhooks scoped to one conversation: target type and URL. Use for \"Which webhooks fire for Twilio conversation CHaaa\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"conversation_sid":{"description":"The SID of the conversation: 'CH' followed by 32 hex characters.","maxLength":34,"title":"Conversation Sid","type":"string"},"page_size":{"anyOf":[{"maximum":1000,"minimum":1,"type":"integer"},{"type":"null"}],"default":50,"description":"How many results to return (1 to 1000).","title":"Page Size"},"page_token":{"anyOf":[{"maxLength":300,"type":"string"},{"type":"null"}],"default":null,"description":"Paging token: the PageToken value inside meta.next_page_url from the previous answer (leave empty for the first page).","title":"Page Token"}},"required":["conversation_sid"],"title":"list_conversation_webhooksArguments","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_push_credentials":{"post":{"operationId":"list_push_credentials","summary":"List push notification credentials (FCM or APNs) registered for Conversations: name, type and sandbox flag. Secrets are ","description":"List push notification credentials (FCM or APNs) registered for Conversations: name, type and sandbox flag. Secrets are not returned. Use for \"Which push credentials are set up for Twilio Conversations\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"page_size":{"anyOf":[{"maximum":1000,"minimum":1,"type":"integer"},{"type":"null"}],"default":50,"description":"How many results to return (1 to 1000).","title":"Page Size"},"page_token":{"anyOf":[{"maxLength":300,"type":"string"},{"type":"null"}],"default":null,"description":"Paging token: the PageToken value inside meta.next_page_url from the previous answer (leave empty for the first page).","title":"Page Token"}},"title":"list_push_credentialsArguments","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_address_configurations":{"post":{"operationId":"list_address_configurations","summary":"List the address configurations that route SMS, WhatsApp or other channel addresses into Conversations. Use for \"Which c","description":"List the address configurations that route SMS, WhatsApp or other channel addresses into Conversations. Use for \"Which channel addresses are wired into Twilio Conversations\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"type":{"anyOf":[{"maxLength":30,"type":"string"},{"type":"null"}],"default":null,"description":"Only configurations of this channel type, for example sms, whatsapp, messenger or gbm.","title":"Type"},"page_size":{"anyOf":[{"maximum":1000,"minimum":1,"type":"integer"},{"type":"null"}],"default":50,"description":"How many results to return (1 to 1000).","title":"Page Size"},"page_token":{"anyOf":[{"maxLength":300,"type":"string"},{"type":"null"}],"default":null,"description":"Paging token: the PageToken value inside meta.next_page_url from the previous answer (leave empty for the first page).","title":"Page Token"}},"title":"list_address_configurationsArguments","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}}}}