• Simple Message Notification

smn
  1. Help Center
  2. Simple Message Notification
  3. API Reference
  4. APIs
  5. Subscription Operations
  6. Adding a Subscription

Adding a Subscription

Description

  • API name

    Subscribe

  • Function

    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. A topic supports a maximum of 10,000 subscriptions. 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

  • URI format

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

  • Parameter description

    Parameter

    Mandatory

    Type

    Description

    project_id

    Yes

    String

    Project ID

    topic_urn

    Yes

    String

    Resource identifier of a topic, which is unique

Request

  • Parameter description

    Parameter

    Mandatory

    Type

    Description

    endpoint

    Yes

    String

    Message endpoint

    NOTE:

    For an HTTP subscription, the endpoint starts with http://.

    For an HTTPS subscription, the endpoint starts with https://.

    For an email subscription, the endpoint is an email address.

    For an SMS subscription, the endpoint is a phone number.

    For a DMS subscription, the endpoint is a message queue.

    protocol

    Yes

    String

    Protocol of the message endpoint

    NOTE:

    Currently, email, sms, dms, http, and https are supported.

    remark

    No

    String

    Description of the subscription

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

  • Request example
    POST /v2/{project_id}/notifications/topics/urn:smn:regionId:762bdb3251034f268af0e395c53ea09b:test_topic_v1/subscriptions
    {
        "protocol": "email", 
        "endpoint": "xxx@xxx.com", 
        "remark": "O&M"
    } 

Response

  • Parameter description

    Parameter

    Type

    Description

    request_id

    String

    Request ID, which is unique

    subscription_urn

    String

    Resource identifier of a subscription, which is unique

  • Response example
    {
        "request_id": "fdbabe38ead6482b8574f82a3d1168e9",
        "subscription_urn": "urn:smn:regionId:762bdb3251034f268af0e395c53ea09b:test_topic_v1:2e778e84408e44058e6cbc6d3c377837"
    }

Returned Value

See section Returned Value.

Error Code

See section Error Code.