--- updatedAt: 2026-04-14T09:46:15.000Z agentTools: projectIndex: https://developers.newo.ai/llms.txt --- # Integrations and connectors Integrations define the communication channels available on the Newo platform, while connectors are the configured, runnable instances of those integrations that connect an agent to the outside world. ## Integration vs connector Understanding the distinction between an integration and a connector is fundamental to working with the Newo platform. * **Integration** — A channel type that defines a category of external communication. For example, `newo_voice` is an integration that represents telephone conversations using Newo's native voice system. An integration specifies what settings are available, what events it can emit, and what commands it can receive. Integrations are provided by the platform and cannot be created by users. * **Connector** — A configured, named instance of an integration. A single integration can have multiple connectors, each with its own settings and identifier. For example, a `newo_voice` integration might have two connectors: `sales_line` and `support_line`, each configured with different phone numbers and voice settings. Connectors are created, configured, and managed by users. Think of it this way: the integration is the blueprint, and the connector is the built, operational instance. ::: **🗒️ NOTE** Every connector belongs to exactly one integration and is uniquely identified by the combination of its `integration_idn` and `connector_idn`. This pair is used throughout the platform to route events, target commands, and filter sessions. ::: ## Integration fields | **Field** | **Description** | | ----------------------------------- | ------------------------------------------------------------------------------------------------------------ | | `id` | The unique UUID of the integration | | `idn` | The identifying name (e.g., `newo_voice`, `telegram`). Used as the `integration_idn` throughout the platform | | `title` | A human-readable display name | | `is_disabled` | Whether the integration is currently disabled for the account | | `integration_settings_descriptions` | Schema definitions for integration-level settings (shared across all connectors) | | `connector_settings_descriptions` | Schema definitions for per-connector settings | | `outgoing_events_descriptions` | Events this integration can emit (e.g., `user_message`, `conversation_started`) | | `incoming_commands_descriptions` | Commands this integration can receive (e.g., `send_message`, `make_call`) | ## Integration identifier reference Each integration is identified by a unique `idn` string. The table below lists all integration identifiers currently available on the platform. | **Identifier** | **Title** | **Category** | **Description** | | ------------------ | ---------------- | --------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | `api` | API | API/Webhook | Allows third-party applications to interact with agents through Newo's API commands. Supports webhook configuration for receiving events | | `google_calendar` | Google Calendar | Productivity | Allows an agent to manage scheduling and appointments through Google Calendar | | `http` | HTTP | API/Webhook | Allows an agent to send generic HTTP/API requests using the `send_request` command. Responses return through the `magic_http_response` event | | `magic_api` | Magic API | API/Webhook | Allows an agent to interact with external APIs through the Magic API bot. Responses return through the `magic_api_response` event | | `magic_browser` | Magic Browser | Automation | Allows an agent to perform automated web browser actions such as searching, making bookings, and setting meetings. Responses return through the `magic_browser_response` event | | `newo_chat` | Newo Chat | Chat | Provides text-only or avatar-based web chat for embedding on websites. Supports the Talking Head feature for visual avatar conversations | | `newo_sms` | Newo SMS | Messaging | Allows an agent to send and receive text messages using Newo's native SMS system | | `newo_voice` | Newo Voice | Voice/Telephony | Enables telephone conversations using Newo's native voice system with SIP/Telnyx support, configurable STT/TTS providers, and voice-to-voice modes | | `program_timer` | Program Timer | Automation | Allows setting up programmable timers at defined intervals. Fires the `timer` event when triggered | | `sandbox` | Sandbox | Development | Provides text communication via the built-in Sandbox chat window for testing and development | | `telegram` | Telegram | Chat | Allows an agent to communicate via a Telegram chatbot | | `twilio` | Twilio | Voice/Telephony | Enables telephone conversations with an agent using Twilio's voice infrastructure | | `twilio_messenger` | Twilio Messenger | Messaging | Allows an agent to send SMS notifications and communicate via text message using Twilio | | `vapi` | Vapi | Voice/Telephony | Enables telephone conversations with additional voice options and more realistic-sounding agent voices | ::: **🗒️ NOTE** The `system` integration identifier also appears in flow event configurations. It is an internal platform integration used for system-level events like `session_started` and `session_ended`. It does not appear in the user-facing integrations list. ::: ## Connector fields | **Field** | **Description** | | ----------------- | --------------------------------------------------------------------- | | `id` | The unique UUID of the connector | | `title` | A human-readable display name | | `connector_idn` | The identifying name for this specific connector (e.g., `sales_line`) | | `integration_idn` | The identifying name of the parent integration (e.g., `newo_voice`) | | `status` | Current operational state: `running` or `stopped` | | `settings` | Array of key-value settings applied to this connector | ## Connector lifecycle Creating and managing a connector follows a three-phase lifecycle: **create**, **configure**, and **activate**. ### 1. Create To create a connector, provide the parent integration's ID along with the connector data: ``` POST v1/integrations/{integrationId}/connectors ``` The request body requires three fields: `title` (human-readable name), `connector_idn` (unique identifying name), and `settings` (initial settings values as an array of `idn`/`value` pairs). The `connector_idn` must be unique within its integration and follow Newo's identifying name conventions (lowercase, underscores, no spaces). ::: **🗒️ NOTE** When creating a connector through the **Integrations** page in the Newo Builder UI, the platform automatically runs the connector after creation. Through the API, creation and activation are separate steps. ::: ### 2. Configure Both integrations and connectors have two levels of settings: * **Integration-level settings** — Shared across all connectors of that integration. For example, a Twilio integration might require `account_sid` and `auth_token` at the integration level. These are configured via: ``` POST v1/integrations/{integrationId}/settings ``` * **Connector-level settings** — Specific to a single connector instance. For example, a voice connector might have settings for phone number, STT provider, and TTS provider. These are configured via: ``` POST v1/integrations/connectors/{connectorId}/settings ``` Each setting has two fields: `idn` (the setting identifier) and `value` (the setting value). The available settings for each level are defined by the integration's `integration_settings_descriptions` and `connector_settings_descriptions` arrays. Each description entry (`ISettingPreset`) includes metadata such as the control type, value type, whether the field is required, and its possible values. ### 3. Activate Once created and configured, a connector must be started before it processes events: ``` POST v1/integrations/connectors/{connectorId}/run ``` A running connector can be paused at any time: ``` POST v1/integrations/connectors/{connectorId}/stop ``` The connector's `status` field reflects its current state as either `running` or `stopped`. Only running connectors receive and emit events. ### Deleting a connector A connector can be removed entirely: ``` DELETE v1/integrations/connectors/{connectorId} ``` ## How integrations relate to events and flows Integrations, connectors, events, and flows form a connected pipeline that drives agent behavior. ### Event subscriptions A flow's event subscriptions determine which incoming events trigger which skills. Each event subscription can be scoped to a specific integration and connector: ```yaml events: - idn: user_message_event skill_idn: HandleUserMessage integration_idn: newo_chat connector_idn: website_chat interrupt_mode: queue ``` In this example, the `user_message_event` subscription is configured so that only `user_message` events arriving through the `newo_chat` integration's `website_chat` connector will trigger the `HandleUserMessage` skill. When `integration_idn` is set to `null`, the event subscription matches events from any integration. Similarly, when `connector_idn` is `null`, it matches events from any connector within the specified integration. ### Event and command routing Each integration declares the events it can emit and the commands it accepts. This relationship works in two directions: * **Inbound (events):** When a user sends a chat message, the `newo_chat` integration emits a `user_message` event. The flow engine matches this event against subscriptions and dispatches it to the appropriate skill. * **Outbound (commands):** When a skill needs to send a reply, it uses a `SendCommand` action targeting a specific integration and connector. For example, sending an HTTP request uses the `send_request` command on the `http` integration. The `integration_idn/connector_idn` pair acts as a routing address throughout the system. This pair appears in event data, command targets, session metadata, and analytics filters. ### Channel mapping For customer-facing applications, integrations map to broader channel categories: | **Channel** | **Integration identifiers** | | ----------- | --------------------------- | | Chat | `newo_chat`, `telegram` | | Phone | `newo_voice`, `vapi` | | SMS | `twilio_messenger` | This mapping is used for session filtering, analytics grouping, and portal-level channel configuration. ## Cross-references * See **Integration Identifier List** for the complete reference of all integration identifiers * See **Event Identifier List** for all event identifiers that integrations can emit * See **Command Identifier List** for all command identifiers that integrations accept * See **Flow** for how event subscriptions connect integrations to agent logic