Integrations
Generate chat OAuth URL
deprecated
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, MS Teams, and Webex.
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.
POST
/
v1
/
integrations
/
chat
/
oauth
Generate chat OAuth URL
curl --request POST \
--url https://api.novu.co/v1/integrations/chat/oauth \
--header 'Authorization: <api-key>' \
--header 'Content-Type: application/json' \
--data '
{
"integrationIdentifier": "<string>",
"subscriberId": "subscriber-123",
"connectionIdentifier": "slack-connection-abc123",
"context": {},
"scope": [
"chat:write",
"chat:write.public",
"channels:read",
"groups:read",
"users:read",
"users:read.email",
"incoming-webhook"
],
"userScope": [
"identity.basic"
],
"mode": "link_user",
"connectionMode": "shared",
"autoLinkUser": true
}
'import requests
url = "https://api.novu.co/v1/integrations/chat/oauth"
payload = {
"integrationIdentifier": "<string>",
"subscriberId": "subscriber-123",
"connectionIdentifier": "slack-connection-abc123",
"context": {},
"scope": ["chat:write", "chat:write.public", "channels:read", "groups:read", "users:read", "users:read.email", "incoming-webhook"],
"userScope": ["identity.basic"],
"mode": "link_user",
"connectionMode": "shared",
"autoLinkUser": True
}
headers = {
"Authorization": "<api-key>",
"Content-Type": "application/json"
}
response = requests.post(url, json=payload, headers=headers)
print(response.text)const options = {
method: 'POST',
headers: {Authorization: '<api-key>', 'Content-Type': 'application/json'},
body: JSON.stringify({
integrationIdentifier: '<string>',
subscriberId: 'subscriber-123',
connectionIdentifier: 'slack-connection-abc123',
context: {},
scope: [
'chat:write',
'chat:write.public',
'channels:read',
'groups:read',
'users:read',
'users:read.email',
'incoming-webhook'
],
userScope: ['identity.basic'],
mode: 'link_user',
connectionMode: 'shared',
autoLinkUser: true
})
};
fetch('https://api.novu.co/v1/integrations/chat/oauth', options)
.then(res => res.json())
.then(res => console.log(res))
.catch(err => console.error(err));<?php
$curl = curl_init();
curl_setopt_array($curl, [
CURLOPT_URL => "https://api.novu.co/v1/integrations/chat/oauth",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_ENCODING => "",
CURLOPT_MAXREDIRS => 10,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => "POST",
CURLOPT_POSTFIELDS => json_encode([
'integrationIdentifier' => '<string>',
'subscriberId' => 'subscriber-123',
'connectionIdentifier' => 'slack-connection-abc123',
'context' => [
],
'scope' => [
'chat:write',
'chat:write.public',
'channels:read',
'groups:read',
'users:read',
'users:read.email',
'incoming-webhook'
],
'userScope' => [
'identity.basic'
],
'mode' => 'link_user',
'connectionMode' => 'shared',
'autoLinkUser' => true
]),
CURLOPT_HTTPHEADER => [
"Authorization: <api-key>",
"Content-Type: application/json"
],
]);
$response = curl_exec($curl);
$err = curl_error($curl);
curl_close($curl);
if ($err) {
echo "cURL Error #:" . $err;
} else {
echo $response;
}package main
import (
"fmt"
"strings"
"net/http"
"io"
)
func main() {
url := "https://api.novu.co/v1/integrations/chat/oauth"
payload := strings.NewReader("{\n \"integrationIdentifier\": \"<string>\",\n \"subscriberId\": \"subscriber-123\",\n \"connectionIdentifier\": \"slack-connection-abc123\",\n \"context\": {},\n \"scope\": [\n \"chat:write\",\n \"chat:write.public\",\n \"channels:read\",\n \"groups:read\",\n \"users:read\",\n \"users:read.email\",\n \"incoming-webhook\"\n ],\n \"userScope\": [\n \"identity.basic\"\n ],\n \"mode\": \"link_user\",\n \"connectionMode\": \"shared\",\n \"autoLinkUser\": true\n}")
req, _ := http.NewRequest("POST", url, payload)
req.Header.Add("Authorization", "<api-key>")
req.Header.Add("Content-Type", "application/json")
res, _ := http.DefaultClient.Do(req)
defer res.Body.Close()
body, _ := io.ReadAll(res.Body)
fmt.Println(string(body))
}HttpResponse<String> response = Unirest.post("https://api.novu.co/v1/integrations/chat/oauth")
.header("Authorization", "<api-key>")
.header("Content-Type", "application/json")
.body("{\n \"integrationIdentifier\": \"<string>\",\n \"subscriberId\": \"subscriber-123\",\n \"connectionIdentifier\": \"slack-connection-abc123\",\n \"context\": {},\n \"scope\": [\n \"chat:write\",\n \"chat:write.public\",\n \"channels:read\",\n \"groups:read\",\n \"users:read\",\n \"users:read.email\",\n \"incoming-webhook\"\n ],\n \"userScope\": [\n \"identity.basic\"\n ],\n \"mode\": \"link_user\",\n \"connectionMode\": \"shared\",\n \"autoLinkUser\": true\n}")
.asString();require 'uri'
require 'net/http'
url = URI("https://api.novu.co/v1/integrations/chat/oauth")
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\": \"<string>\",\n \"subscriberId\": \"subscriber-123\",\n \"connectionIdentifier\": \"slack-connection-abc123\",\n \"context\": {},\n \"scope\": [\n \"chat:write\",\n \"chat:write.public\",\n \"channels:read\",\n \"groups:read\",\n \"users:read\",\n \"users:read.email\",\n \"incoming-webhook\"\n ],\n \"userScope\": [\n \"identity.basic\"\n ],\n \"mode\": \"link_user\",\n \"connectionMode\": \"shared\",\n \"autoLinkUser\": true\n}"
response = http.request(request)
puts response.read_body{
"url": "https://slack.com/oauth/v2/authorize?state=..."
}{
"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
API key authentication. Allowed headers-- "Authorization: ApiKey <novu_secret_key>".
Headers
A header for idempotency purposes
Body
application/json
Integration identifier
The subscriber ID to link the channel connection to. For Slack: Required for incoming webhook endpoints, optional for workspace connections. For MS Teams: Optional. Admin consent is tenant-wide and can be associated with a subscriber for organizational purposes.
Example:
"subscriber-123"
Identifier of the channel connection that will be created. It is generated automatically if not provided.
Example:
"slack-connection-abc123"
Show child attributes
Show child attributes
Slack only: OAuth scopes to request during authorization. These define the permissions your Slack integration will have. If not specified, default scopes will be used: chat:write, chat:write.public, channels:read, groups:read, users:read, users:read.email. Webex: OAuth scopes to request during authorization. Defaults to: spark:messages_write, spark:rooms_read, spark:people_read, spark:memberships_read, spark:kms. MS Teams: This parameter is ignored. MS Teams uses admin consent with pre-configured permissions in Azure AD. Note: The generated OAuth URL expires after 5 minutes.
Example:
[
"chat:write",
"chat:write.public",
"channels:read",
"groups:read",
"users:read",
"users:read.email",
"incoming-webhook"
]
Slack only, link_user mode: User-level OAuth scopes to request during authorization. Used when mode is "link_user" to identify the Slack user via "Sign in with Slack". If not specified, defaults to: identity.basic.
Example:
["identity.basic"]
OAuth flow mode. Use "connect" (default) to create a workspace channel connection, or "link_user" to identify the subscriber's Slack user ID without creating a connection.
Available options:
connect, link_user Example:
"link_user"
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"
When true, after the workspace/tenant connection is created the OAuth flow also links the subscriber who clicked "Connect" as a personal endpoint. For Slack, this uses the authed_user.id already returned by oauth.v2.access — no extra redirect. For Webex, this uses the authenticated Webex person returned by people/me — no extra redirect. For MS Teams, this triggers a second OAuth redirect for delegated user-identity consent. Defaults to false when omitted; the SlackConnectButton and MsTeamsConnectButton SDK components default this to true.
Example:
true
Response
Created
The OAuth authorization URL for the chat provider. For Slack: https://slack.com/oauth/v2/authorize?... For MS Teams: https://login.microsoftonline.com/.../adminconsent?... This URL should be presented to the user to authorize the integration. Expires after 5 minutes.
Example:
"https://slack.com/oauth/v2/authorize?state=..."
Was this page helpful?
⌘I
Generate chat OAuth URL
curl --request POST \
--url https://api.novu.co/v1/integrations/chat/oauth \
--header 'Authorization: <api-key>' \
--header 'Content-Type: application/json' \
--data '
{
"integrationIdentifier": "<string>",
"subscriberId": "subscriber-123",
"connectionIdentifier": "slack-connection-abc123",
"context": {},
"scope": [
"chat:write",
"chat:write.public",
"channels:read",
"groups:read",
"users:read",
"users:read.email",
"incoming-webhook"
],
"userScope": [
"identity.basic"
],
"mode": "link_user",
"connectionMode": "shared",
"autoLinkUser": true
}
'import requests
url = "https://api.novu.co/v1/integrations/chat/oauth"
payload = {
"integrationIdentifier": "<string>",
"subscriberId": "subscriber-123",
"connectionIdentifier": "slack-connection-abc123",
"context": {},
"scope": ["chat:write", "chat:write.public", "channels:read", "groups:read", "users:read", "users:read.email", "incoming-webhook"],
"userScope": ["identity.basic"],
"mode": "link_user",
"connectionMode": "shared",
"autoLinkUser": True
}
headers = {
"Authorization": "<api-key>",
"Content-Type": "application/json"
}
response = requests.post(url, json=payload, headers=headers)
print(response.text)const options = {
method: 'POST',
headers: {Authorization: '<api-key>', 'Content-Type': 'application/json'},
body: JSON.stringify({
integrationIdentifier: '<string>',
subscriberId: 'subscriber-123',
connectionIdentifier: 'slack-connection-abc123',
context: {},
scope: [
'chat:write',
'chat:write.public',
'channels:read',
'groups:read',
'users:read',
'users:read.email',
'incoming-webhook'
],
userScope: ['identity.basic'],
mode: 'link_user',
connectionMode: 'shared',
autoLinkUser: true
})
};
fetch('https://api.novu.co/v1/integrations/chat/oauth', options)
.then(res => res.json())
.then(res => console.log(res))
.catch(err => console.error(err));<?php
$curl = curl_init();
curl_setopt_array($curl, [
CURLOPT_URL => "https://api.novu.co/v1/integrations/chat/oauth",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_ENCODING => "",
CURLOPT_MAXREDIRS => 10,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => "POST",
CURLOPT_POSTFIELDS => json_encode([
'integrationIdentifier' => '<string>',
'subscriberId' => 'subscriber-123',
'connectionIdentifier' => 'slack-connection-abc123',
'context' => [
],
'scope' => [
'chat:write',
'chat:write.public',
'channels:read',
'groups:read',
'users:read',
'users:read.email',
'incoming-webhook'
],
'userScope' => [
'identity.basic'
],
'mode' => 'link_user',
'connectionMode' => 'shared',
'autoLinkUser' => true
]),
CURLOPT_HTTPHEADER => [
"Authorization: <api-key>",
"Content-Type: application/json"
],
]);
$response = curl_exec($curl);
$err = curl_error($curl);
curl_close($curl);
if ($err) {
echo "cURL Error #:" . $err;
} else {
echo $response;
}package main
import (
"fmt"
"strings"
"net/http"
"io"
)
func main() {
url := "https://api.novu.co/v1/integrations/chat/oauth"
payload := strings.NewReader("{\n \"integrationIdentifier\": \"<string>\",\n \"subscriberId\": \"subscriber-123\",\n \"connectionIdentifier\": \"slack-connection-abc123\",\n \"context\": {},\n \"scope\": [\n \"chat:write\",\n \"chat:write.public\",\n \"channels:read\",\n \"groups:read\",\n \"users:read\",\n \"users:read.email\",\n \"incoming-webhook\"\n ],\n \"userScope\": [\n \"identity.basic\"\n ],\n \"mode\": \"link_user\",\n \"connectionMode\": \"shared\",\n \"autoLinkUser\": true\n}")
req, _ := http.NewRequest("POST", url, payload)
req.Header.Add("Authorization", "<api-key>")
req.Header.Add("Content-Type", "application/json")
res, _ := http.DefaultClient.Do(req)
defer res.Body.Close()
body, _ := io.ReadAll(res.Body)
fmt.Println(string(body))
}HttpResponse<String> response = Unirest.post("https://api.novu.co/v1/integrations/chat/oauth")
.header("Authorization", "<api-key>")
.header("Content-Type", "application/json")
.body("{\n \"integrationIdentifier\": \"<string>\",\n \"subscriberId\": \"subscriber-123\",\n \"connectionIdentifier\": \"slack-connection-abc123\",\n \"context\": {},\n \"scope\": [\n \"chat:write\",\n \"chat:write.public\",\n \"channels:read\",\n \"groups:read\",\n \"users:read\",\n \"users:read.email\",\n \"incoming-webhook\"\n ],\n \"userScope\": [\n \"identity.basic\"\n ],\n \"mode\": \"link_user\",\n \"connectionMode\": \"shared\",\n \"autoLinkUser\": true\n}")
.asString();require 'uri'
require 'net/http'
url = URI("https://api.novu.co/v1/integrations/chat/oauth")
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\": \"<string>\",\n \"subscriberId\": \"subscriber-123\",\n \"connectionIdentifier\": \"slack-connection-abc123\",\n \"context\": {},\n \"scope\": [\n \"chat:write\",\n \"chat:write.public\",\n \"channels:read\",\n \"groups:read\",\n \"users:read\",\n \"users:read.email\",\n \"incoming-webhook\"\n ],\n \"userScope\": [\n \"identity.basic\"\n ],\n \"mode\": \"link_user\",\n \"connectionMode\": \"shared\",\n \"autoLinkUser\": true\n}"
response = http.request(request)
puts response.read_body{
"url": "https://slack.com/oauth/v2/authorize?state=..."
}{
"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."