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
integrations_controller_auto_configure_integration - Auto-configure an integration for inbound webhooks
set_as_primary - Update integration as primary
list_active - List active integrations
generate_connect_o_auth_url - Generate OAuth URL for a workspace/tenant connection
generate_link_user_o_auth_url - Generate OAuth URL to link a subscriber user identity
~~generate_chat_o_auth_url~~ - Generate chat OAuth URL ⚠️ Deprecated

list

List all the channels integrations created in the organization

Example Usage

from novu_py import Novu


with Novu(
    secret_key="YOUR_SECRET_KEY_HERE",
) as novu:

    res = novu.integrations.list()

    # Handle response
    print(res)

Parameters

Parameter	Type	Required	Description
`idempotency_key`	Optional[str]	➖	A header for idempotency purposes
`retries`	Optional[utils.RetryConfig]	➖	Configuration to override the default retry behavior of the client.

Response

models.IntegrationsControllerListIntegrationsResponse

Errors

Error Type	Status Code	Content Type
models.ErrorDto	414	application/json
models.ErrorDto	400, 401, 403, 404, 405, 409, 413, 415	application/json
models.ValidationErrorDto	422	application/json
models.ErrorDto	500	application/json
models.APIError	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

from novu_py import Novu


with Novu(
    secret_key="YOUR_SECRET_KEY_HERE",
) as novu:

    res = novu.integrations.create(create_integration_request_dto={})

    # Handle response
    print(res)

Parameters

Parameter	Type	Required	Description
`create_integration_request_dto`	models.CreateIntegrationRequestDto	✔️	N/A
`idempotency_key`	Optional[str]	➖	A header for idempotency purposes
`retries`	Optional[utils.RetryConfig]	➖	Configuration to override the default retry behavior of the client.

Response

models.IntegrationsControllerCreateIntegrationResponse

Errors

Error Type	Status Code	Content Type
models.ErrorDto	414	application/json
models.ErrorDto	400, 401, 403, 404, 405, 409, 413, 415	application/json
models.ValidationErrorDto	422	application/json
models.ErrorDto	500	application/json
models.APIError	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

from novu_py import Novu


with Novu(
    secret_key="YOUR_SECRET_KEY_HERE",
) as novu:

    res = novu.integrations.update(integration_id="<id>", update_integration_request_dto={})

    # Handle response
    print(res)

Parameters

Parameter	Type	Required	Description
`integration_id`	str	✔️	N/A
`update_integration_request_dto`	models.UpdateIntegrationRequestDto	✔️	N/A
`idempotency_key`	Optional[str]	➖	A header for idempotency purposes
`retries`	Optional[utils.RetryConfig]	➖	Configuration to override the default retry behavior of the client.

Response

models.IntegrationsControllerUpdateIntegrationByIDResponse

Errors

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

delete

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

Example Usage

from novu_py import Novu


with Novu(
    secret_key="YOUR_SECRET_KEY_HERE",
) as novu:

    res = novu.integrations.delete(integration_id="<id>")

    # Handle response
    print(res)

Parameters

Parameter	Type	Required	Description
`integration_id`	str	✔️	N/A
`idempotency_key`	Optional[str]	➖	A header for idempotency purposes
`retries`	Optional[utils.RetryConfig]	➖	Configuration to override the default retry behavior of the client.

Response

models.IntegrationsControllerRemoveIntegrationResponse

Errors

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

integrations_controller_auto_configure_integration

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

from novu_py import Novu


with Novu(
    secret_key="YOUR_SECRET_KEY_HERE",
) as novu:

    res = novu.integrations.integrations_controller_auto_configure_integration(integration_id="<id>")

    # Handle response
    print(res)

Parameters

Parameter	Type	Required	Description
`integration_id`	str	✔️	N/A
`idempotency_key`	Optional[str]	➖	A header for idempotency purposes
`retries`	Optional[utils.RetryConfig]	➖	Configuration to override the default retry behavior of the client.

Response

models.IntegrationsControllerAutoConfigureIntegrationResponse

Errors

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

set_as_primary

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

from novu_py import Novu


with Novu(
    secret_key="YOUR_SECRET_KEY_HERE",
) as novu:

    res = novu.integrations.set_as_primary(integration_id="<id>")

    # Handle response
    print(res)

Parameters

Parameter	Type	Required	Description
`integration_id`	str	✔️	N/A
`idempotency_key`	Optional[str]	➖	A header for idempotency purposes
`retries`	Optional[utils.RetryConfig]	➖	Configuration to override the default retry behavior of the client.

Response

models.IntegrationsControllerSetIntegrationAsPrimaryResponse

Errors

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

list_active

List all the active integrations created in the organization

Example Usage

from novu_py import Novu


with Novu(
    secret_key="YOUR_SECRET_KEY_HERE",
) as novu:

    res = novu.integrations.list_active()

    # Handle response
    print(res)

Parameters

Parameter	Type	Required	Description
`idempotency_key`	Optional[str]	➖	A header for idempotency purposes
`retries`	Optional[utils.RetryConfig]	➖	Configuration to override the default retry behavior of the client.

Response

models.IntegrationsControllerGetActiveIntegrationsResponse

Errors

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

generate_connect_o_auth_url

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

import novu_py
from novu_py import Novu


with Novu(
    secret_key="YOUR_SECRET_KEY_HERE",
) as novu:

    res = novu.integrations.generate_connect_o_auth_url(generate_connect_oauth_url_request_dto={
        "subscriber_id": "subscriber-123",
        "integration_identifier": "<value>",
        "connection_identifier": "slack-connection-abc123",
        "context": {
            "key": "org-acme",
        },
        "scope": [
            "chat:write",
            "chat:write.public",
            "channels:read",
        ],
        "connection_mode": novu_py.GenerateConnectOauthURLRequestDtoConnectionMode.SHARED,
        "auto_link_user": True,
    })

    # Handle response
    print(res)

Parameters

Parameter	Type	Required	Description
`generate_connect_oauth_url_request_dto`	models.GenerateConnectOauthURLRequestDto	✔️	N/A
`idempotency_key`	Optional[str]	➖	A header for idempotency purposes
`retries`	Optional[utils.RetryConfig]	➖	Configuration to override the default retry behavior of the client.

Response

models.IntegrationsControllerGenerateConnectOAuthURLResponse

Errors

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

generate_link_user_o_auth_url

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

from novu_py import Novu


with Novu(
    secret_key="YOUR_SECRET_KEY_HERE",
) as novu:

    res = novu.integrations.generate_link_user_o_auth_url(generate_link_user_oauth_url_request_dto={
        "subscriber_id": "subscriber-123",
        "integration_identifier": "<value>",
        "connection_identifier": "slack-connection-abc123",
        "context": {
            "key": "org-acme",
        },
        "user_scope": [
            "identity.basic",
        ],
    })

    # Handle response
    print(res)

Parameters

Parameter	Type	Required	Description
`generate_link_user_oauth_url_request_dto`	models.GenerateLinkUserOauthURLRequestDto	✔️	N/A
`idempotency_key`	Optional[str]	➖	A header for idempotency purposes
`retries`	Optional[utils.RetryConfig]	➖	Configuration to override the default retry behavior of the client.

Response

models.IntegrationsControllerGenerateLinkUserOAuthURLResponse

Errors

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

generate_chat_o_auth_url

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

import novu_py
from novu_py import Novu


with Novu(
    secret_key="YOUR_SECRET_KEY_HERE",
) as novu:

    res = novu.integrations.generate_chat_o_auth_url(generate_chat_oauth_url_request_dto={
        "subscriber_id": "subscriber-123",
        "integration_identifier": "<value>",
        "connection_identifier": "slack-connection-abc123",
        "context": {
            "key": "org-acme",
        },
        "scope": [
            "chat:write",
            "chat:write.public",
            "channels:read",
            "groups:read",
            "users:read",
            "users:read.email",
            "incoming-webhook",
        ],
        "user_scope": [
            "identity.basic",
        ],
        "mode": novu_py.Mode.LINK_USER,
        "connection_mode": novu_py.GenerateChatOauthURLRequestDtoConnectionMode.SHARED,
        "auto_link_user": True,
    })

    # Handle response
    print(res)

Parameters

Parameter	Type	Required	Description
`generate_chat_oauth_url_request_dto`	models.GenerateChatOauthURLRequestDto	✔️	N/A
`idempotency_key`	Optional[str]	➖	A header for idempotency purposes
`retries`	Optional[utils.RetryConfig]	➖	Configuration to override the default retry behavior of the client.

Response

models.IntegrationsControllerGetChatOAuthURLResponse

Errors

Error Type	Status Code	Content Type
models.ErrorDto	414	application/json
models.ErrorDto	400, 401, 403, 404, 405, 409, 413, 415	application/json
models.ValidationErrorDto	422	application/json
models.ErrorDto	500	application/json
models.APIError	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

integrations_controller_auto_configure_integration

Example Usage

Parameters

Response

Errors

set_as_primary

Example Usage

Parameters

Response

Errors

list_active

Example Usage

Parameters

Response

Errors

generate_connect_o_auth_url

Example Usage

Parameters

Response

Errors

generate_link_user_o_auth_url

Example Usage

Parameters

Response

Errors

generate_chat_o_auth_url

Example Usage

Parameters

Response

Errors