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:

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