Help Center> Simple Message Notification> API Reference> APIs> Subscription Operations> Adding a Subscription
View PDF

Adding a Subscription

Function

This API is used to add a subscription to a specified topic. If the status of the subscription is unconfirmed, a confirmation message is sent to the subscriber. After confirming the subscription, the subscriber can receive notification messages published to the topic. By default, 10,000 subscriptions can be added to a topic. However, in a high-concurrency scenario, which is rare, extra subscriptions may be added successfully. The API is idempotent. If the added subscription already exists, a successful result and status code 200 are returned. Otherwise, the status code is 201.

URI

POST /v2/{project_id}/notifications/topics/{topic_urn}/subscriptions

Table 1 Path parameters

Parameter

Mandatory

Type

Description

project_id

Yes

String

Specifies the project ID.

See Obtaining a Project ID.

topic_urn

Yes

String

Specifies the resource identifier of the topic, which is unique. To obtain the resource identifier, see Querying Topics.

Request Parameters

Table 2 Request header parameter

Parameter

Mandatory

Type

Description

X-Auth-Token

Yes

String

Specifies the user token.

It can be obtained by calling the IAM API (value of X-Subject-Token in the response header).
Table 3 Request body parameters

Parameter

Mandatory

Type

Description

protocol

Yes

String

Specifies the subscription protocol. (Different protocols indicate different types of endpoints to receive messages.) The following protocols are supported:

  • email: The endpoints are email address.
  • sms: The endpoints are phone numbers.
  • functionstage: The endpoints are FunctionGraph functions.
  • http and https: The endpoints are URLs.
  • callnotify: The endpoints are phone numbers.

endpoint

Yes

String
  • For an HTTPS subscription, the endpoint starts with https://.
  • For an email subscription, the endpoint must be an email address.
  • For an SMS subscription, the endpoint must be a phone number.
  • For a FunctionStage subscription, the endpoint must be a function.
  • For a DMS subscription, the endpoint must be a message queue.
  • For an application subscription, the endpoint must be a mobile device added to a platform application.
  • For a voice notification subscription, the endpoint is a phone number.

remark

No

String

Specifies the remarks.

The remarks must be a UTF-8-coded character string containing up to 128 bytes.

Response Parameters

Status code: 201

Table 4 Response body parameters

Parameter

Type

Description

request_id

String

Specifies the request ID, which is unique.

subscription_urn

String

Specifies the resource identifier of a subscription, which is unique.

Status code: 400

Table 5 Response body parameters

Parameter

Type

Description

request_id

String

Specifies the request ID, which is unique.

code

String

Specifies the error code.

message

String

Describes the error message.

Status code: 403

Table 6 Response body parameters

Parameter

Type

Description

request_id

String

Specifies the request ID, which is unique.

code

String

Specifies the error code.

message

String

Describes the error message.

Status code: 404

Table 7 Response body parameters

Parameter

Type

Description

request_id

String

Specifies the request ID, which is unique.

code

String

Specifies the error code.

message

String

Describes the error message.

Status code: 500

Table 8 Response body parameters

Parameter

Type

Description

request_id

String

Specifies the request ID, which is unique.

code

String

Specifies the error code.

message

String

Describes the error message.

Example Requests

Adding a subscription to a specified topic

POST https://{SMN_Endpoint}/v2/{project_id}/notifications/topics/urn:smn:regionId:762bdb3251034f268af0e395c53ea09b:test_topic_v1/subscriptions

{
  "protocol" : "email",
  "endpoint" : "xxx@xxx.com",
  "remark": "O&M"
}

Example Responses

Status code: 201

OK

[ {
  "request_id" : "6a63a18b8bab40ffb71ebd9cb80d0085",
  "subscription_urn" : "urn:smn:regionId:762bdb3251034f268af0e395c53ea09b:test_topic_v1:2e778e84408e44058e6cbc6d3c377837"
} ]

Status Codes

Status Code

Description

201

OK

400

Bad Request

403

Unauthorized

404

Not Found

500

Internal Server Error

Error Codes

See Error Codes.

Parent topic: Subscription Operations