Push, notifications

Send message

post

This API allows partner apps to send notifications or messages to Toss users. A user authentication token is required, and it must include the scope permission to send messages to users. All messages, including test sends, can be sent only after being approved through copy review.

Business error code

The errors below are returned with HTTP 200 and resultType: FAIL.

errorCode

Description

5004

This is an unapproved message template. To send messages, template review approval is required.

4034

There is no workspace, or you don't have permission to access the workspace

4010

Authentication information not found.

4095

You have exceeded the request limit. Please try again later.

This API can pass through error codes from the linked internal system as-is. Treat undocumented errorCode as failures and refer to the reason message.

Request limit: 15,000 per minute per app, 10 per minute per user

Authorizations

mutualTLS

This is client-certificate-based mTLS authentication issued to the partner. The mini app is identified by the certificate's CN. Refer to the Use the server API document for how to issue and manage certificates.

Header parameters

x-toss-user-keystringOptional

It's a key for authenticating users. It can be obtained through the Get user information API

Example: 12345678

x-anon-keystringOptional

It's a key for authenticating users. You can issue it with the User.getAnonymousKey function in the mini app SDK

Example: kQ7pL2mZxN9wRt5vB8yD3jF6cA1

Body

Defines the message to send to the user. It includes which message template to use and the data to be inserted into the template.

templateSetCodestringRequired

This is the message template code to use. Enter one of the template codes registered in advance.

Example: ALERT_OTP_TEMPLATE

Responses

200

Message sent successfully

application/json

400

The request body is not in the correct format. Check the field-by-field details in error.data.errorDetails.

application/json

500

This is an unclassified server error. If it keeps failing, please contact the partner support channel.

application/json

post/api-partner/v1/apps-in-toss/messenger/send-message

POST /api-partner/v1/apps-in-toss/messenger/send-message HTTP/1.1
Host: apps-in-toss-api.toss.im
x-toss-user-key: {userKey}
Content-Type: application/json

{
  "templateSetCode": "ALERT_OTP_TEMPLATE",
  "context": {
    "userName": "홍길동",
    "otp": "123456"
  }
}

{
  "resultType": "SUCCESS",
  "success": {
    "detail": {
      "sentAlimtalk": [],
      "sentFriendtalk": [
        {
          "contentId": "MSG_FRIENDTALK_0001"
        }
      ],
      "sentInbox": [
        {
          "contentId": "MSG_INBOX_0001"
        }
      ],
      "sentPush": [
        {
          "contentId": "MSG_PUSH_0001"
        },
        {
          "contentId": "MSG_PUSH_0002"
        }
      ],
      "sentSms": [
        {
          "contentId": "MSG_SMS_0001"
        }
      ]
    },
    "fail": {
      "sentAlimtalk": [],
      "sentFriendtalk": [
        {
          "contentId": "MSG_FRIENDTALK_0001"
        }
      ],
      "sentInbox": [
        {
          "contentId": "MSG_INBOX_0001"
        }
      ],
      "sentPush": [
        {
          "contentId": "MSG_PUSH_0001"
        },
        {
          "contentId": "MSG_PUSH_0002"
        }
      ],
      "sentSms": [
        {
          "contentId": "MSG_SMS_0001"
        }
      ]
    },
    "msgCount": 5,
    "sentAlimtalkCount": 0,
    "sentFriendtalkCount": 1,
    "sentInboxCount": 1,
    "sentPushCount": 2,
    "sentSmsCount": 1
  }
}

Send bulk messages

post

We send the same template message in bulk to multiple users. Use this when sending at least 50 messages in bulk. You can send up to 2,500 messages per request.

Business error code

The errors below are returned with HTTP 200 and resultType: FAIL.

errorCode

Description

5004

This is an unapproved message template. To send messages, template review approval is required.

4034

There is no workspace, or you don't have permission to access the workspace

4095

You have exceeded the request limit. Please try again later.

This API can pass through error codes from the linked internal system as-is. Treat undocumented errorCode as failures and refer to the reason message.

Request limit: 3,000 per minute per app

Authorizations

mutualTLS

Body

Defines messages to send to users in bulk. It includes both the message template to use and the list of data to put into the template.

templateSetCodestringRequired

This is the message template code to use. Enter one of the template codes registered in advance.

Example: ALERT_OTP_TEMPLATE

Responses

200

This is the result of request processing. Use the value of resultType to distinguish between success and failure.

application/json

400

The request body is not in the correct format. Check the field-by-field details in error.data.errorDetails.

application/json

500

This is an unclassified server error. If it keeps failing, please contact the partner support channel.

application/json

post/api-partner/v1/apps-in-toss/messenger/send-bulk-message

POST /api-partner/v1/apps-in-toss/messenger/send-bulk-message HTTP/1.1
Host: apps-in-toss-api.toss.im
Content-Type: application/json

{
  "templateSetCode": "ALERT_OTP_TEMPLATE",
  "contextList": [
    {
      "userKey": 12345678,
      "context": {
        "userName": "홍길동",
        "otp": "123456"
      }
    }
  ]
}

{
  "resultType": "SUCCESS",
  "success": {
    "detail": {
      "sentAlimtalk": [],
      "sentFriendtalk": [
        {
          "contentId": "MSG_FRIENDTALK_0001"
        }
      ],
      "sentInbox": [
        {
          "contentId": "MSG_INBOX_0001"
        }
      ],
      "sentPush": [
        {
          "contentId": "MSG_PUSH_0001"
        },
        {
          "contentId": "MSG_PUSH_0002"
        }
      ],
      "sentSms": [
        {
          "contentId": "MSG_SMS_0001"
        }
      ]
    },
    "fail": {
      "sentAlimtalk": [],
      "sentFriendtalk": [
        {
          "contentId": "MSG_FRIENDTALK_0001"
        }
      ],
      "sentInbox": [
        {
          "contentId": "MSG_INBOX_0001"
        }
      ],
      "sentPush": [
        {
          "contentId": "MSG_PUSH_0001"
        },
        {
          "contentId": "MSG_PUSH_0002"
        }
      ],
      "sentSms": [
        {
          "contentId": "MSG_SMS_0001"
        }
      ]
    },
    "msgCount": 5,
    "sentAlimtalkCount": 0,
    "sentFriendtalkCount": 1,
    "sentInboxCount": 1,
    "sentPushCount": 2,
    "sentSmsCount": 1
  }
}

Send test message

post

This API allows partner apps to receive messages and check whether bundles work properly before review. A user authentication token is required, and it must include the scope permission to send messages to users. All messages, including test sends, can be sent only after being approved through copy review.

Business error code

The errors below are returned with HTTP 200 and resultType: FAIL.

errorCode

Description

4010

Authentication information not found.

4095

You have exceeded the request limit. Please try again later.

This API can pass through error codes from the linked internal system as-is. Treat undocumented errorCode as failures and refer to the reason message.

Request limit: 3,000 per minute per app

Authorizations

mutualTLS

Header parameters

x-toss-user-keystringOptional

It's a key for authenticating users. It can be obtained through the Get user information API

Example: 12345678

x-anon-keystringOptional

It's a key for authenticating users. You can issue it with the User.getAnonymousKey function in the mini app SDK

Example: kQ7pL2mZxN9wRt5vB8yD3jF6cA1

Body

Defines the message to send to the user. It includes which message template to use and the data to be inserted into the template.

deploymentIdstringRequired

This is the identifier of the bundle to use when testing message sending. It is in UUID format and can be found in the bundle uploaded in the Apps in Toss console's app release menu.

Example: 019abfe8-fd68-7021-9cdc-30d6053cc009

templateSetCodestringRequired

This is the message template code to use. Enter one of the template codes registered in advance.

Example: ALERT_OTP_TEMPLATE

Responses

200

Message sent successfully

application/json

400

The request body is not in the correct format. Check the field-by-field details in error.data.errorDetails.

application/json

500

This is an unclassified server error. If it keeps failing, please contact the partner support channel.

application/json

post/api-partner/v1/apps-in-toss/messenger/send-test-message

POST /api-partner/v1/apps-in-toss/messenger/send-test-message HTTP/1.1
Host: apps-in-toss-api.toss.im
x-toss-user-key: {userKey}
Content-Type: application/json

{
  "templateSetCode": "ALERT_OTP_TEMPLATE",
  "deploymentId": "019abfe8-fd68-7021-9cdc-30d6053cc009",
  "context": {
    "userName": "홍길동",
    "otp": "123456"
  }
}

{
  "resultType": "SUCCESS",
  "success": {
    "detail": {
      "sentAlimtalk": [],
      "sentFriendtalk": [
        {
          "contentId": "MSG_FRIENDTALK_0001"
        }
      ],
      "sentInbox": [
        {
          "contentId": "MSG_INBOX_0001"
        }
      ],
      "sentPush": [
        {
          "contentId": "MSG_PUSH_0001"
        },
        {
          "contentId": "MSG_PUSH_0002"
        }
      ],
      "sentSms": [
        {
          "contentId": "MSG_SMS_0001"
        }
      ]
    },
    "fail": {
      "sentAlimtalk": [],
      "sentFriendtalk": [
        {
          "contentId": "MSG_FRIENDTALK_0001"
        }
      ],
      "sentInbox": [
        {
          "contentId": "MSG_INBOX_0001"
        }
      ],
      "sentPush": [
        {
          "contentId": "MSG_PUSH_0001"
        },
        {
          "contentId": "MSG_PUSH_0002"
        }
      ],
      "sentSms": [
        {
          "contentId": "MSG_SMS_0001"
        }
      ]
    },
    "msgCount": 5,
    "sentAlimtalkCount": 0,
    "sentFriendtalkCount": 1,
    "sentInboxCount": 1,
    "sentPushCount": 2,
    "sentSmsCount": 1
  }
}

PreviousToss Pay

NextPromotion (Toss Points)

Was this helpful?