推送、通知

发送消息

post

此 API 允许合作伙伴应用向 Toss 用户发送通知或消息。需要用户认证令牌，并且必须包含向用户发送消息的 scope 权限。包括测试发送在内，所有消息都必须在通过文案审核批准后才能发送。

业务错误代码

以下错误会以 HTTP 200 和 resultType: FAIL 响应。

errorCode

说明

5004

这是未经批准的消息模板。发送消息前需要通过模板审核批准。

4034

没有工作区，或没有访问该工作区的权限

4010

找不到认证信息。

4095

请求已超出限制。请稍后再试。

此 API 可以原样传递所集成内部系统的错误代码。未文档化的 errorCode 会被视为失败，请参考 reason 消息。

请求限制: 每个应用每分钟 15,000 次，每个用户每分钟 10 次

授权

mutualTLS

这是基于为合作伙伴签发的客户端证书的 mTLS 认证。通过证书的 CN 来识别迷你应用。证书签发·管理方法请参考使用服务器 API 文档。

头参数

x-toss-user-keystring可选

用于验证用户的密钥。可通过获取用户信息 API 获取

Example: 12345678

x-anon-keystring可选

用于验证用户的密钥。可通过迷你应用 SDK 的 User.getAnonymousKey 函数获取

Example: kQ7pL2mZxN9wRt5vB8yD3jF6cA1

请求体

定义要发送给用户的消息。将要使用的消息模板及其模板数据一并包含。

templateSetCodestring必填

这是要使用的消息模板代码。请填入预先注册的模板代码之一。

Example: ALERT_OTP_TEMPLATE

响应

200

消息发送成功

application/json

或

400

请求正文不符合格式。请在error.data.errorDetails中查看各字段详情。

application/json

500

未分类的服务器错误。如果持续失败，请联系合作伙伴支持渠道。

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
  }
}

批量发送消息

post

向多个用户批量发送相同模板的消息。请在批量发送至少 50 条以上时使用。一次请求最多可发送 2,500 条。

业务错误代码

以下错误会以 HTTP 200 和 resultType: FAIL 响应。

errorCode

说明

5004

这是未经批准的消息模板。发送消息前需要通过模板审核批准。

4034

没有工作区，或没有访问该工作区的权限

4095

请求已超出限制。请稍后再试。

此 API 可以原样传递所集成内部系统的错误代码。未文档化的 errorCode 会被视为失败，请参考 reason 消息。

请求限制: 每个应用每分钟 3,000 次

授权

mutualTLS

这是基于为合作伙伴签发的客户端证书的 mTLS 认证。通过证书的 CN 来识别迷你应用。证书签发·管理方法请参考使用服务器 API 文档。

请求体

定义批量发送给用户的消息。它包含要使用的消息模板以及将填入模板的数据列表。

templateSetCodestring必填

这是要使用的消息模板代码。请填入预先注册的模板代码之一。

Example: ALERT_OTP_TEMPLATE

响应

200

这是请求处理结果。请根据 resultType 值区分成功/失败。

application/json

或

400

请求正文不符合格式。请在error.data.errorDetails中查看各字段详情。

application/json

500

未分类的服务器错误。如果持续失败，请联系合作伙伴支持渠道。

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
  }
}

发送测试消息

post

此 API 允许合作伙伴应用接收消息，并在审核前确认 bundle 是否正常工作。需要用户认证令牌，并且必须包含向用户发送消息的 scope 权限。包括测试发送在内，所有消息都必须在通过文案审核批准后才能发送。

业务错误代码

以下错误会以 HTTP 200 和 resultType: FAIL 响应。

errorCode

说明

4010

找不到认证信息。

4095

请求已超出限制。请稍后再试。

此 API 可以原样传递所集成内部系统的错误代码。未文档化的 errorCode 会被视为失败，请参考 reason 消息。

请求限制: 每个应用每分钟 3,000 次

授权

mutualTLS

这是基于为合作伙伴签发的客户端证书的 mTLS 认证。通过证书的 CN 来识别迷你应用。证书签发·管理方法请参考使用服务器 API 文档。

头参数

x-toss-user-keystring可选

用于验证用户的密钥。可通过获取用户信息 API 获取

Example: 12345678

x-anon-keystring可选

用于验证用户的密钥。可通过迷你应用 SDK 的 User.getAnonymousKey 函数获取

Example: kQ7pL2mZxN9wRt5vB8yD3jF6cA1

请求体

定义要发送给用户的消息。将要使用的消息模板及其模板数据一并包含。

deploymentIdstring必填

这是用于消息发送测试时使用的 bundle 的识别值。为 UUID 格式，可在 Apps in Toss 控制台的应用发布菜单中上传的 bundle 中查看。

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

templateSetCodestring必填

这是要使用的消息模板代码。请填入预先注册的模板代码之一。

Example: ALERT_OTP_TEMPLATE

响应

200

消息发送成功

application/json

或

400

请求正文不符合格式。请在error.data.errorDetails中查看各字段详情。

application/json

500

未分类的服务器错误。如果持续失败，请联系合作伙伴支持渠道。

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
  }
}

上一页Toss Pay

下一页促销（Toss 积分）

这有帮助吗？