Issue a URL to link a subscriber chat identity

POST

integrations

channel-endpoints

link

TypeScript

import { Novu } from "@novu/api";

const novu = new Novu({
  secretKey: "YOUR_SECRET_KEY_HERE",
});

async function run() {
  const result = await novu.integrations.linkChannelEndpoint({
    integrationIdentifier: "telegram-bot",
    subscriberId: "subscriber-123",
  });

  console.log(result);
}

run();

using Novu;
using Novu.Models.Components;

var sdk = new NovuSDK(secretKey: "YOUR_SECRET_KEY_HERE");

var res = await sdk.Integrations.LinkChannelEndpointAsync(linkChannelEndpointRequestDto: new LinkChannelEndpointRequestDto() {
    IntegrationIdentifier = "telegram-bot",
    SubscriberId = "subscriber-123",
});

// handle response

declare(strict_types=1);

require 'vendor/autoload.php';

use novu;
use novu\Models\Components;

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

$linkChannelEndpointRequestDto = new Components\LinkChannelEndpointRequestDto(
    integrationIdentifier: 'telegram-bot',
    subscriberId: 'subscriber-123',
);

$response = $sdk->integrations->linkChannelEndpoint(
    linkChannelEndpointRequestDto: $linkChannelEndpointRequestDto
);

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

from novu_py import Novu


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

    res = novu.integrations.link_channel_endpoint(link_channel_endpoint_request_dto={
        "integration_identifier": "telegram-bot",
        "subscriber_id": "subscriber-123",
    })

    # Handle response
    print(res)

package main

import(
	"context"
	"github.com/novuhq/novu-go/v3"
	"github.com/novuhq/novu-go/v3/models/components"
	"log"
)

func main() {
    ctx := context.Background()

    s := v3.New(
        v3.WithSecurity("YOUR_SECRET_KEY_HERE"),
    )

    res, err := s.Integrations.LinkChannelEndpoint(ctx, components.LinkChannelEndpointRequestDto{
        IntegrationIdentifier: "telegram-bot",
        SubscriberID: "subscriber-123",
    }, nil)
    if err != nil {
        log.Fatal(err)
    }
    if res.LinkChannelEndpointResponseDto != nil {
        // handle response
    }
}

curl --request POST \
  --url https://api.novu.co/v1/integrations/channel-endpoints/link \
  --header 'Authorization: <api-key>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "integrationIdentifier": "telegram-bot",
  "subscriberId": "subscriber-123"
}
'

const options = {
  method: 'POST',
  headers: {Authorization: '<api-key>', 'Content-Type': 'application/json'},
  body: JSON.stringify({integrationIdentifier: 'telegram-bot', subscriberId: 'subscriber-123'})
};

fetch('https://api.novu.co/v1/integrations/channel-endpoints/link', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

HttpResponse<String> response = Unirest.post("https://api.novu.co/v1/integrations/channel-endpoints/link")
  .header("Authorization", "<api-key>")
  .header("Content-Type", "application/json")
  .body("{\n  \"integrationIdentifier\": \"telegram-bot\",\n  \"subscriberId\": \"subscriber-123\"\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://api.novu.co/v1/integrations/channel-endpoints/link")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["Authorization"] = '<api-key>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"integrationIdentifier\": \"telegram-bot\",\n  \"subscriberId\": \"subscriber-123\"\n}"

response = http.request(request)
puts response.read_body

{
  "url": "https://t.me/MyBot?start=AbCdEfGhIjKlMnOpQrStUvWxYz012345",
  "providerMetadata": {
    "botUsername": "MyBot",
    "expiresAt": "2026-06-23T12:00:00.000Z"
  }
}

{
  "statusCode": 404,
  "timestamp": "2024-12-12T13:00:00Z",
  "path": "/api/v1/resource",
  "message": "xx xx xx ",
  "ctx": {
    "workflowId": "some_wf_id",
    "stepId": "some_wf_id"
  },
  "errorId": "abc123"
}

{
  "statusCode": 404,
  "timestamp": "2024-12-12T13:00:00Z",
  "path": "/api/v1/resource",
  "message": "xx xx xx ",
  "ctx": {
    "workflowId": "some_wf_id",
    "stepId": "some_wf_id"
  },
  "errorId": "abc123"
}

{
  "statusCode": 404,
  "timestamp": "2024-12-12T13:00:00Z",
  "path": "/api/v1/resource",
  "message": "xx xx xx ",
  "ctx": {
    "workflowId": "some_wf_id",
    "stepId": "some_wf_id"
  },
  "errorId": "abc123"
}

{
  "statusCode": 404,
  "timestamp": "2024-12-12T13:00:00Z",
  "path": "/api/v1/resource",
  "message": "xx xx xx ",
  "ctx": {
    "workflowId": "some_wf_id",
    "stepId": "some_wf_id"
  },
  "errorId": "abc123"
}

{
  "statusCode": 404,
  "timestamp": "2024-12-12T13:00:00Z",
  "path": "/api/v1/resource",
  "message": "xx xx xx ",
  "ctx": {
    "workflowId": "some_wf_id",
    "stepId": "some_wf_id"
  },
  "errorId": "abc123"
}

{
  "statusCode": 404,
  "timestamp": "2024-12-12T13:00:00Z",
  "path": "/api/v1/resource",
  "message": "xx xx xx ",
  "ctx": {
    "workflowId": "some_wf_id",
    "stepId": "some_wf_id"
  },
  "errorId": "abc123"
}

{
  "statusCode": 404,
  "timestamp": "2024-12-12T13:00:00Z",
  "path": "/api/v1/resource",
  "message": "xx xx xx ",
  "ctx": {
    "workflowId": "some_wf_id",
    "stepId": "some_wf_id"
  },
  "errorId": "abc123"
}

{
  "statusCode": 404,
  "timestamp": "2024-12-12T13:00:00Z",
  "path": "/api/v1/resource",
  "message": "xx xx xx ",
  "ctx": {
    "workflowId": "some_wf_id",
    "stepId": "some_wf_id"
  },
  "errorId": "abc123"
}

{
  "statusCode": 404,
  "timestamp": "2024-12-12T13:00:00Z",
  "path": "/api/v1/resource",
  "message": "xx xx xx ",
  "ctx": {
    "workflowId": "some_wf_id",
    "stepId": "some_wf_id"
  },
  "errorId": "abc123"
}

{
  "statusCode": 404,
  "timestamp": "2024-12-12T13:00:00Z",
  "path": "/api/v1/resource",
  "errors": {
    "fieldName1": {
      "messages": [
        "Field is required",
        "Must be a valid email address"
      ],
      "value": "invalidEmail"
    },
    "fieldName2": {
      "messages": [
        "Must be at least 18 years old"
      ],
      "value": 17
    },
    "fieldName3": {
      "messages": [
        "Must be a boolean value"
      ],
      "value": true
    },
    "fieldName4": {
      "messages": [
        "Must be a valid object"
      ],
      "value": {
        "key": "value"
      }
    },
    "fieldName5": {
      "messages": [
        "Field is missing"
      ],
      "value": null
    },
    "fieldName6": {
      "messages": [
        "Undefined value"
      ]
    }
  },
  "message": "xx xx xx ",
  "ctx": {
    "workflowId": "some_wf_id",
    "stepId": "some_wf_id"
  },
  "errorId": "abc123"
}

"API rate limit exceeded"

{
  "statusCode": 404,
  "timestamp": "2024-12-12T13:00:00Z",
  "path": "/api/v1/resource",
  "message": "xx xx xx ",
  "ctx": {
    "workflowId": "some_wf_id",
    "stepId": "some_wf_id"
  },
  "errorId": "abc123"
}

"Please wait some time, then try again."

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

Integration identifier for the chat provider integration

Example:

"telegram-bot"

subscriberId

string

required

External subscriber identifier to link to their chat identity

Example:

"subscriber-123"

Response

url

string

required

URL the subscriber opens to link their chat identity (OAuth URL or deep link)

Example:

"https://t.me/MyBot?start=AbCdEfGhIjKlMnOpQrStUvWxYz012345"

providerMetadata

object

Provider-specific metadata returned alongside the link URL

Example:

{
  "botUsername": "MyBot",
  "expiresAt": "2026-06-23T12:00:00.000Z"
}

Generate OAuth URL for a workspace/tenant connection

Generate OAuth URL to link a subscriber user identity

⌘I

TypeScript

import { Novu } from "@novu/api";

const novu = new Novu({
  secretKey: "YOUR_SECRET_KEY_HERE",
});

async function run() {
  const result = await novu.integrations.linkChannelEndpoint({
    integrationIdentifier: "telegram-bot",
    subscriberId: "subscriber-123",
  });

  console.log(result);
}

run();

using Novu;
using Novu.Models.Components;

var sdk = new NovuSDK(secretKey: "YOUR_SECRET_KEY_HERE");

var res = await sdk.Integrations.LinkChannelEndpointAsync(linkChannelEndpointRequestDto: new LinkChannelEndpointRequestDto() {
    IntegrationIdentifier = "telegram-bot",
    SubscriberId = "subscriber-123",
});

// handle response

declare(strict_types=1);

require 'vendor/autoload.php';

use novu;
use novu\Models\Components;

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

$linkChannelEndpointRequestDto = new Components\LinkChannelEndpointRequestDto(
    integrationIdentifier: 'telegram-bot',
    subscriberId: 'subscriber-123',
);

$response = $sdk->integrations->linkChannelEndpoint(
    linkChannelEndpointRequestDto: $linkChannelEndpointRequestDto
);

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

from novu_py import Novu


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

    res = novu.integrations.link_channel_endpoint(link_channel_endpoint_request_dto={
        "integration_identifier": "telegram-bot",
        "subscriber_id": "subscriber-123",
    })

    # Handle response
    print(res)

package main

import(
	"context"
	"github.com/novuhq/novu-go/v3"
	"github.com/novuhq/novu-go/v3/models/components"
	"log"
)

func main() {
    ctx := context.Background()

    s := v3.New(
        v3.WithSecurity("YOUR_SECRET_KEY_HERE"),
    )

    res, err := s.Integrations.LinkChannelEndpoint(ctx, components.LinkChannelEndpointRequestDto{
        IntegrationIdentifier: "telegram-bot",
        SubscriberID: "subscriber-123",
    }, nil)
    if err != nil {
        log.Fatal(err)
    }
    if res.LinkChannelEndpointResponseDto != nil {
        // handle response
    }
}

curl --request POST \
  --url https://api.novu.co/v1/integrations/channel-endpoints/link \
  --header 'Authorization: <api-key>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "integrationIdentifier": "telegram-bot",
  "subscriberId": "subscriber-123"
}
'

const options = {
  method: 'POST',
  headers: {Authorization: '<api-key>', 'Content-Type': 'application/json'},
  body: JSON.stringify({integrationIdentifier: 'telegram-bot', subscriberId: 'subscriber-123'})
};

fetch('https://api.novu.co/v1/integrations/channel-endpoints/link', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

HttpResponse<String> response = Unirest.post("https://api.novu.co/v1/integrations/channel-endpoints/link")
  .header("Authorization", "<api-key>")
  .header("Content-Type", "application/json")
  .body("{\n  \"integrationIdentifier\": \"telegram-bot\",\n  \"subscriberId\": \"subscriber-123\"\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://api.novu.co/v1/integrations/channel-endpoints/link")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["Authorization"] = '<api-key>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"integrationIdentifier\": \"telegram-bot\",\n  \"subscriberId\": \"subscriber-123\"\n}"

response = http.request(request)
puts response.read_body

{
  "url": "https://t.me/MyBot?start=AbCdEfGhIjKlMnOpQrStUvWxYz012345",
  "providerMetadata": {
    "botUsername": "MyBot",
    "expiresAt": "2026-06-23T12:00:00.000Z"
  }
}

{
  "statusCode": 404,
  "timestamp": "2024-12-12T13:00:00Z",
  "path": "/api/v1/resource",
  "message": "xx xx xx ",
  "ctx": {
    "workflowId": "some_wf_id",
    "stepId": "some_wf_id"
  },
  "errorId": "abc123"
}

{
  "statusCode": 404,
  "timestamp": "2024-12-12T13:00:00Z",
  "path": "/api/v1/resource",
  "message": "xx xx xx ",
  "ctx": {
    "workflowId": "some_wf_id",
    "stepId": "some_wf_id"
  },
  "errorId": "abc123"
}

{
  "statusCode": 404,
  "timestamp": "2024-12-12T13:00:00Z",
  "path": "/api/v1/resource",
  "message": "xx xx xx ",
  "ctx": {
    "workflowId": "some_wf_id",
    "stepId": "some_wf_id"
  },
  "errorId": "abc123"
}

{
  "statusCode": 404,
  "timestamp": "2024-12-12T13:00:00Z",
  "path": "/api/v1/resource",
  "message": "xx xx xx ",
  "ctx": {
    "workflowId": "some_wf_id",
    "stepId": "some_wf_id"
  },
  "errorId": "abc123"
}

{
  "statusCode": 404,
  "timestamp": "2024-12-12T13:00:00Z",
  "path": "/api/v1/resource",
  "message": "xx xx xx ",
  "ctx": {
    "workflowId": "some_wf_id",
    "stepId": "some_wf_id"
  },
  "errorId": "abc123"
}

{
  "statusCode": 404,
  "timestamp": "2024-12-12T13:00:00Z",
  "path": "/api/v1/resource",
  "message": "xx xx xx ",
  "ctx": {
    "workflowId": "some_wf_id",
    "stepId": "some_wf_id"
  },
  "errorId": "abc123"
}

{
  "statusCode": 404,
  "timestamp": "2024-12-12T13:00:00Z",
  "path": "/api/v1/resource",
  "message": "xx xx xx ",
  "ctx": {
    "workflowId": "some_wf_id",
    "stepId": "some_wf_id"
  },
  "errorId": "abc123"
}

{
  "statusCode": 404,
  "timestamp": "2024-12-12T13:00:00Z",
  "path": "/api/v1/resource",
  "message": "xx xx xx ",
  "ctx": {
    "workflowId": "some_wf_id",
    "stepId": "some_wf_id"
  },
  "errorId": "abc123"
}

{
  "statusCode": 404,
  "timestamp": "2024-12-12T13:00:00Z",
  "path": "/api/v1/resource",
  "message": "xx xx xx ",
  "ctx": {
    "workflowId": "some_wf_id",
    "stepId": "some_wf_id"
  },
  "errorId": "abc123"
}

{
  "statusCode": 404,
  "timestamp": "2024-12-12T13:00:00Z",
  "path": "/api/v1/resource",
  "errors": {
    "fieldName1": {
      "messages": [
        "Field is required",
        "Must be a valid email address"
      ],
      "value": "invalidEmail"
    },
    "fieldName2": {
      "messages": [
        "Must be at least 18 years old"
      ],
      "value": 17
    },
    "fieldName3": {
      "messages": [
        "Must be a boolean value"
      ],
      "value": true
    },
    "fieldName4": {
      "messages": [
        "Must be a valid object"
      ],
      "value": {
        "key": "value"
      }
    },
    "fieldName5": {
      "messages": [
        "Field is missing"
      ],
      "value": null
    },
    "fieldName6": {
      "messages": [
        "Undefined value"
      ]
    }
  },
  "message": "xx xx xx ",
  "ctx": {
    "workflowId": "some_wf_id",
    "stepId": "some_wf_id"
  },
  "errorId": "abc123"
}

"API rate limit exceeded"

{
  "statusCode": 404,
  "timestamp": "2024-12-12T13:00:00Z",
  "path": "/api/v1/resource",
  "message": "xx xx xx ",
  "ctx": {
    "workflowId": "some_wf_id",
    "stepId": "some_wf_id"
  },
  "errorId": "abc123"
}

"Please wait some time, then try again."

Getting Started

Events

Subscribers

Inbox

Topics

Notifications

Workflows

Translations

Contexts

Environments

Environment Variables

Messages

Integrations

Channel Connections

Channel Endpoints

Activity

Layouts

Contexts

Environments

Activity

Layouts

Subscribers

Topics

Translations

Workflows

Channel Connections

Channel Endpoints

Domains

Environment Variables

Events

Integrations

Messages

Notifications

Issue a URL to link a subscriber chat identity

Authorizations

Headers

Body

Response