Skip to main content
POST
/
v1
/
channel-connections
PHP
declare(strict_types=1);

require 'vendor/autoload.php';

use novu;
use novu\Models\Components;

$sdk = novu\Novu::builder()
    ->setSecurity(
        'YOUR_SECRET_KEY_HERE'
    )
    ->build();

$createChannelConnectionRequestDto = new Components\CreateChannelConnectionRequestDto(
    identifier: 'slack-prod-user123-abc4',
    subscriberId: 'subscriber-123',
    context: [
        'key' => 'org-acme',
    ],
    connectionMode: Components\ConnectionMode::Shared,
    integrationIdentifier: 'slack-prod',
    workspace: new Components\WorkspaceDto(
        id: 'T123456',
        name: 'Acme HQ',
    ),
    auth: new Components\AuthDto(
        accessToken: 'Workspace access token',
    ),
);

$response = $sdk->channelConnections->create(
    createChannelConnectionRequestDto: $createChannelConnectionRequestDto
);

if ($response->getChannelConnectionResponseDto !== null) {
    // handle response
}
{
  "identifier": "<string>",
  "providerId": "slack",
  "integrationIdentifier": "slack-prod",
  "subscriberId": "subscriber-123",
  "contextKeys": [
    "tenant:org-123",
    "region:us-east-1"
  ],
  "workspace": {
    "id": "T123456",
    "name": "Acme HQ"
  },
  "auth": {
    "accessToken": "Workspace access token"
  },
  "createdAt": "<string>",
  "updatedAt": "<string>"
}

Authorizations

Authorization
string
header
required

API key authentication. Allowed headers-- "Authorization: ApiKey <novu_secret_key>".

Headers

idempotency-key
string

A header for idempotency purposes

Body

application/json
integrationIdentifier
string
required

The identifier of the integration to use for this channel connection.

Example:

"slack-prod"

workspace
object
required
auth
object
required
identifier
string

The unique identifier for the channel connection. If not provided, one will be generated automatically.

Example:

"slack-prod-user123-abc4"

subscriberId
string

The subscriber ID to link the channel connection to

Example:

"subscriber-123"

context
object
connectionMode
enum<string>

Connection mode that determines how the channel connection is scoped. Use "subscriber" (default) to associate the connection with a specific subscriber. Use "shared" to associate the connection with a context instead of a subscriber — subscriberId will not be stored on the connection.

Available options:
subscriber,
shared
Example:

"shared"

Response

Created

identifier
string
required

The unique identifier of the channel endpoint.

channel
enum<string> | null
required

The channel type (email, sms, push, chat, etc.).

Available options:
in_app,
email,
sms,
chat,
push
providerId
enum<string> | null
required

The provider identifier (e.g., sendgrid, twilio, slack, etc.).

Available options:
emailjs,
mailgun,
mailjet,
mandrill,
nodemailer,
postmark,
sendgrid,
sendinblue,
ses,
netcore,
infobip-email,
resend,
plunk,
mailersend,
mailtrap,
clickatell,
outlook365,
novu-email,
sparkpost,
email-webhook,
braze,
novu-email-agent,
nexmo,
plivo,
sms77,
sms-central,
sns,
telnyx,
twilio,
gupshup,
firetext,
infobip-sms,
burst-sms,
bulk-sms,
isend-sms,
forty-six-elks,
kannel,
maqsam,
termii,
africas-talking,
novu-sms,
sendchamp,
generic-sms,
clicksend,
bandwidth,
messagebird,
simpletexting,
azure-sms,
ring-central,
brevo-sms,
eazy-sms,
mobishastra,
afro-message,
unifonic,
smsmode,
imedia,
sinch,
isendpro-sms,
cm-telecom,
fcm,
apns,
expo,
one-signal,
pushpad,
push-webhook,
pusher-beams,
appio,
novu,
slack,
discord,
msteams,
mattermost,
ryver,
zulip,
grafana-on-call,
getstream,
rocket-chat,
whatsapp-business,
chat-webhook,
novu-slack,
telegram,
anthropic,
novu-anthropic,
anthropic-aws
Example:

"slack"

integrationIdentifier
string | null
required

The identifier of the integration to use for this channel endpoint.

Example:

"slack-prod"

subscriberId
string | null
required

The subscriber ID to which the channel connection is linked

Example:

"subscriber-123"

contextKeys
string[]
required

The context of the channel connection

Example:
["tenant:org-123", "region:us-east-1"]
workspace
object
required
auth
object
required
createdAt
string
required

The timestamp indicating when the channel endpoint was created, in ISO 8601 format.

updatedAt
string
required

The timestamp indicating when the channel endpoint was last updated, in ISO 8601 format.