Integrations

Overview

With the help of the Integration Store, you can easily integrate your favorite delivery provider. During the runtime of the API, the Integrations Store is responsible for storing the configurations of all the providers. https://docs.novu.co/platform/integrations/overview

Available Operations

list - List all integrations
create - Create an integration
update - Update an integration
delete - Delete an integration
integrationsControllerAutoConfigureIntegration - Auto-configure an integration for inbound webhooks
setAsPrimary - Update integration as primary
listActive - List active integrations
generateConnectOAuthUrl - Generate OAuth URL for a workspace/tenant connection
generateLinkUserOAuthUrl - Generate OAuth URL to link a subscriber user identity
~~generateChatOAuthUrl~~ - Generate chat OAuth URL ⚠️ Deprecated

list

List all the channels integrations created in the organization

Example Usage

declare(strict_types=1);

require 'vendor/autoload.php';

use novu;

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



$response = $sdk->integrations->list(

);

if ($response->integrationResponseDtos !== null) {
    // handle response
}

Parameters

Parameter	Type	Required	Description
`idempotencyKey`	?string	➖	A header for idempotency purposes

Response

?Operations\IntegrationsControllerListIntegrationsResponse

Errors

Error Type	Status Code	Content Type
Errors\ErrorDto	414	application/json
Errors\ErrorDto	400, 401, 403, 404, 405, 409, 413, 415	application/json
Errors\ValidationErrorDto	422	application/json
Errors\ErrorDto	500	application/json
Errors\APIException	4XX, 5XX	/

create

Create an integration for the current environment the user is based on the API key provided. Each provider supports different credentials, check the provider documentation for more details.

Example Usage

declare(strict_types=1);

require 'vendor/autoload.php';

use novu;
use novu\Models\Components;

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

$createIntegrationRequestDto = new Components\CreateIntegrationRequestDto();

$response = $sdk->integrations->create(
    createIntegrationRequestDto: $createIntegrationRequestDto
);

if ($response->integrationResponseDto !== null) {
    // handle response
}

Parameters

Parameter	Type	Required	Description
`createIntegrationRequestDto`	Components\CreateIntegrationRequestDto	✔️	N/A
`idempotencyKey`	?string	➖	A header for idempotency purposes

Response

?Operations\IntegrationsControllerCreateIntegrationResponse

Errors

Error Type	Status Code	Content Type
Errors\ErrorDto	414	application/json
Errors\ErrorDto	400, 401, 403, 404, 405, 409, 413, 415	application/json
Errors\ValidationErrorDto	422	application/json
Errors\ErrorDto	500	application/json
Errors\APIException	4XX, 5XX	/

update

Update an integration by its unique key identifier integrationId. Each provider supports different credentials, check the provider documentation for more details.

Example Usage

declare(strict_types=1);

require 'vendor/autoload.php';

use novu;
use novu\Models\Components;

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

$updateIntegrationRequestDto = new Components\UpdateIntegrationRequestDto();

$response = $sdk->integrations->update(
    integrationId: '<id>',
    updateIntegrationRequestDto: $updateIntegrationRequestDto

);

if ($response->integrationResponseDto !== null) {
    // handle response
}

Parameters

Parameter	Type	Required	Description
`integrationId`	string	✔️	N/A
`updateIntegrationRequestDto`	Components\UpdateIntegrationRequestDto	✔️	N/A
`idempotencyKey`	?string	➖	A header for idempotency purposes

Response

?Operations\IntegrationsControllerUpdateIntegrationByIdResponse

Errors

Error Type	Status Code	Content Type
Errors\ErrorDto	414	application/json
Errors\ErrorDto	400, 401, 403, 405, 409, 413, 415	application/json
Errors\ValidationErrorDto	422	application/json
Errors\ErrorDto	500	application/json
Errors\APIException	4XX, 5XX	/

delete

Delete an integration by its unique key identifier integrationId. This action is irreversible.

Example Usage

declare(strict_types=1);

require 'vendor/autoload.php';

use novu;

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



$response = $sdk->integrations->delete(
    integrationId: '<id>'
);

if ($response->integrationResponseDtos !== null) {
    // handle response
}

Parameters

Parameter	Type	Required	Description
`integrationId`	string	✔️	N/A
`idempotencyKey`	?string	➖	A header for idempotency purposes

Response

?Operations\IntegrationsControllerRemoveIntegrationResponse

Errors

Error Type	Status Code	Content Type
Errors\ErrorDto	414	application/json
Errors\ErrorDto	400, 401, 403, 404, 405, 409, 413, 415	application/json
Errors\ValidationErrorDto	422	application/json
Errors\ErrorDto	500	application/json
Errors\APIException	4XX, 5XX	/

integrationsControllerAutoConfigureIntegration

Auto-configure an integration by its unique key identifier integrationId for inbound webhook support. This will automatically generate required webhook signing keys and configure webhook endpoints.

Example Usage

declare(strict_types=1);

require 'vendor/autoload.php';

use novu;

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



$response = $sdk->integrations->integrationsControllerAutoConfigureIntegration(
    integrationId: '<id>'
);

if ($response->autoConfigureIntegrationResponseDto !== null) {
    // handle response
}

Parameters

Parameter	Type	Required	Description
`integrationId`	string	✔️	N/A
`idempotencyKey`	?string	➖	A header for idempotency purposes

Response

?Operations\IntegrationsControllerAutoConfigureIntegrationResponse

Errors

Error Type	Status Code	Content Type
Errors\ErrorDto	414	application/json
Errors\ErrorDto	400, 401, 403, 405, 409, 413, 415	application/json
Errors\ValidationErrorDto	422	application/json
Errors\ErrorDto	500	application/json
Errors\APIException	4XX, 5XX	/

setAsPrimary

Update an integration as primary by its unique key identifier integrationId. This API will set the integration as primary for that channel in the current environment. Primary integration is used to deliver notification for sms and email channels in the workflow.

Example Usage

declare(strict_types=1);

require 'vendor/autoload.php';

use novu;

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



$response = $sdk->integrations->setAsPrimary(
    integrationId: '<id>'
);

if ($response->integrationResponseDto !== null) {
    // handle response
}

Parameters

Parameter	Type	Required	Description
`integrationId`	string	✔️	N/A
`idempotencyKey`	?string	➖	A header for idempotency purposes

Response

?Operations\IntegrationsControllerSetIntegrationAsPrimaryResponse

Errors

Error Type	Status Code	Content Type
Errors\ErrorDto	414	application/json
Errors\ErrorDto	400, 401, 403, 405, 409, 413, 415	application/json
Errors\ValidationErrorDto	422	application/json
Errors\ErrorDto	500	application/json
Errors\APIException	4XX, 5XX	/

listActive

List all the active integrations created in the organization

Example Usage

declare(strict_types=1);

require 'vendor/autoload.php';

use novu;

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



$response = $sdk->integrations->listActive(

);

if ($response->integrationResponseDtos !== null) {
    // handle response
}

Parameters

Parameter	Type	Required	Description
`idempotencyKey`	?string	➖	A header for idempotency purposes

Response

?Operations\IntegrationsControllerGetActiveIntegrationsResponse

Errors

Error Type	Status Code	Content Type
Errors\ErrorDto	414	application/json
Errors\ErrorDto	400, 401, 403, 404, 405, 409, 413, 415	application/json
Errors\ValidationErrorDto	422	application/json
Errors\ErrorDto	500	application/json
Errors\APIException	4XX, 5XX	/

generateConnectOAuthUrl

Generate an OAuth URL that creates a workspace or tenant-level channel connection (Slack workspace install or MS Teams admin consent). The generated URL expires after 5 minutes.

Example Usage

declare(strict_types=1);

require 'vendor/autoload.php';

use novu;
use novu\Models\Components;

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

$generateConnectOauthUrlRequestDto = new Components\GenerateConnectOauthUrlRequestDto(
    subscriberId: 'subscriber-123',
    integrationIdentifier: '<value>',
    connectionIdentifier: 'slack-connection-abc123',
    context: [
        'key' => 'org-acme',
    ],
    scope: [
        'chat:write',
        'chat:write.public',
        'channels:read',
    ],
    connectionMode: Components\GenerateConnectOauthUrlRequestDtoConnectionMode::Shared,
    autoLinkUser: true,
);

$response = $sdk->integrations->generateConnectOAuthUrl(
    generateConnectOauthUrlRequestDto: $generateConnectOauthUrlRequestDto
);

if ($response->generateChatOAuthUrlResponseDto !== null) {
    // handle response
}

Parameters

Parameter	Type	Required	Description
`generateConnectOauthUrlRequestDto`	Components\GenerateConnectOauthUrlRequestDto	✔️	N/A
`idempotencyKey`	?string	➖	A header for idempotency purposes

Response

?Operations\IntegrationsControllerGenerateConnectOAuthUrlResponse

Errors

Error Type	Status Code	Content Type
Errors\ErrorDto	414	application/json
Errors\ErrorDto	400, 401, 403, 404, 405, 409, 413, 415	application/json
Errors\ValidationErrorDto	422	application/json
Errors\ErrorDto	500	application/json
Errors\APIException	4XX, 5XX	/

generateLinkUserOAuthUrl

Generate an OAuth URL that links a specific subscriber to their chat identity (Slack user ID or MS Teams user OID). The generated URL expires after 5 minutes.

Example Usage

declare(strict_types=1);

require 'vendor/autoload.php';

use novu;
use novu\Models\Components;

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

$generateLinkUserOauthUrlRequestDto = new Components\GenerateLinkUserOauthUrlRequestDto(
    subscriberId: 'subscriber-123',
    integrationIdentifier: '<value>',
    connectionIdentifier: 'slack-connection-abc123',
    context: [
        'key' => 'org-acme',
    ],
    userScope: [
        'identity.basic',
    ],
);

$response = $sdk->integrations->generateLinkUserOAuthUrl(
    generateLinkUserOauthUrlRequestDto: $generateLinkUserOauthUrlRequestDto
);

if ($response->generateChatOAuthUrlResponseDto !== null) {
    // handle response
}

Parameters

Parameter	Type	Required	Description
`generateLinkUserOauthUrlRequestDto`	Components\GenerateLinkUserOauthUrlRequestDto	✔️	N/A
`idempotencyKey`	?string	➖	A header for idempotency purposes

Response

?Operations\IntegrationsControllerGenerateLinkUserOAuthUrlResponse

Errors

Error Type	Status Code	Content Type
Errors\ErrorDto	414	application/json
Errors\ErrorDto	400, 401, 403, 404, 405, 409, 413, 415	application/json
Errors\ValidationErrorDto	422	application/json
Errors\ErrorDto	500	application/json
Errors\APIException	4XX, 5XX	/

generateChatOAuthUrl

Deprecated — use POST /integrations/channel-connections/oauth (connect) or POST /integrations/channel-endpoints/oauth (link_user) instead. Generate an OAuth URL for chat integrations like Slack and MS Teams. This URL allows subscribers to authorize the integration, enabling the system to send messages through their chat workspace. The generated URL expires after 5 minutes.

⚠️ DEPRECATED: This will be removed in a future release, please migrate away from it as soon as possible.

Example Usage

declare(strict_types=1);

require 'vendor/autoload.php';

use novu;
use novu\Models\Components;

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

$generateChatOauthUrlRequestDto = new Components\GenerateChatOauthUrlRequestDto(
    subscriberId: 'subscriber-123',
    integrationIdentifier: '<value>',
    connectionIdentifier: 'slack-connection-abc123',
    context: [
        'key' => 'org-acme',
    ],
    scope: [
        'chat:write',
        'chat:write.public',
        'channels:read',
        'groups:read',
        'users:read',
        'users:read.email',
        'incoming-webhook',
    ],
    userScope: [
        'identity.basic',
    ],
    mode: Components\Mode::LinkUser,
    connectionMode: Components\GenerateChatOauthUrlRequestDtoConnectionMode::Shared,
    autoLinkUser: true,
);

$response = $sdk->integrations->generateChatOAuthUrl(
    generateChatOauthUrlRequestDto: $generateChatOauthUrlRequestDto
);

if ($response->generateChatOAuthUrlResponseDto !== null) {
    // handle response
}

Parameters

Parameter	Type	Required	Description
`generateChatOauthUrlRequestDto`	Components\GenerateChatOauthUrlRequestDto	✔️	N/A
`idempotencyKey`	?string	➖	A header for idempotency purposes

Response

?Operations\IntegrationsControllerGetChatOAuthUrlResponse

Errors

Error Type	Status Code	Content Type
Errors\ErrorDto	414	application/json
Errors\ErrorDto	400, 401, 403, 404, 405, 409, 413, 415	application/json
Errors\ValidationErrorDto	422	application/json
Errors\ErrorDto	500	application/json
Errors\APIException	4XX, 5XX	/

FilesExpand file tree

README.md

Latest commit

History

README.md

File metadata and controls

Integrations

Overview

Available Operations

list

Example Usage

Parameters

Response

Errors

create

Example Usage

Parameters

Response

Errors

update

Example Usage

Parameters

Response

Errors

delete

Example Usage

Parameters

Response

Errors

integrationsControllerAutoConfigureIntegration

Example Usage

Parameters

Response

Errors

setAsPrimary

Example Usage

Parameters

Response

Errors

listActive

Example Usage

Parameters

Response

Errors

generateConnectOAuthUrl

Example Usage

Parameters

Response

Errors

generateLinkUserOAuthUrl

Example Usage

Parameters

Response

Errors

generateChatOAuthUrl

Example Usage

Parameters

Response

Errors