Register a Message Bot

    Registers a message bot to be used by the client.
    A message bot is registered on a tenant basis, so you should register its domain if you want to use it on a domain basis.
    You can use a message bot only after registering both its tenant and domain by using the Register a Message Bot and Register a Message Bot Domain APIs.

    You can specify the scope of domains for a bot.
    If the scope is not all domains, only specified domains can be registered.

    You can register bots in multiple languages.
    Add a bot's name, photo and description in multiple languages, and they will be displayed in the language that matches the client's language settings.

    You can also choose a chat type.
    The default is 1:1 chat, and you can enable "Invitation to team/group or 1:N chat room available" using the useGroupJoin parameter.

    You can specify a message receiving server.
    Only HTTPS is accepted for the server, and if the callback URL is set to empty string, it will not send a callback. You can also specify the callbackEvents parameter to selectively receive events you want.
    The event specified by callbackEvents can activate menus that appear at the bottom of a 1:1 chat room.

    Caution

    • You can add up to 300 message bots.
    • A new line character in the name parameter is substituted with a blank space.
    • Self-signed certificates are not allowed in callbackUrl.
    • To see the list of allowed certificate authorities, refer to CA List.

    API Type

    Server API

    Request URL

    https://apis.worksmobile.com/r/{API ID}/message/v1/bot

    HTTP Method

    POST (Content-Type: application/json; charset=UTF-8)

    Request

    common

    Parameter Type Required Description
    name string Y Message bot name
    Max length: 100 characters
    photoUrl string Y The URL of a message bot profile image (PNG format and only HTTPS allowed)
    Max length: 1,000 characters
    description string Y Description of the message bot
    Max length: 100 characters
    managers array\ Y Primary contacts of the message bot (1-3 accounts)
    submanagers array N Secondary contacts of the message bot (up to 3 accounts)
    useGroupJoin boolean N Chat type
    ○ false: 1:1 chat only (default)
    ○ true: Invitation to team/group or 1:N chat room available
    useDomainScope boolean N Specify the scope of domains for a bot.
    ○ false: All domains (default)
    ○ true: Specified domains
    domainIds array\ N Specify domains. It is required if useDomainScope is "true."
    At least one domain should be specified.
    useCallback boolean N Indicates whether to use callbacks.
    ○ false: Don’t use (default)
    ○ true: Use
    callbackUrl string N Specify a message receiving server (HTTPS only). It is required if useCallback is “true.”
    callbackEvents array N Specify an event type to receive. It is required if useCallback is “true.” More event types will be added later.
    ○ "text": Text
    ○ "location": Location information
    ○ "sticker": Sticker
    ○ "image": Image

    multi language

    Parameter Type Required Description
    i18nNames[] array N Multilingual names
    i18nNames[].language string Y Language code
    ○ ko_KR ○ ja_JP ○ zh_CN ○ zh_TW ○ en_US
    i18nNames[].name string Y Name in the language
    Max length: 100 characters
    i18nPhotoUrls[] array N URLs of multilingual images
    i18nPhotoUrls[].language string Y Language code
    ○ ko_KR ○ ja_JP ○ zh_CN ○ zh_TW ○ en_US
    i18nPhotoUrls[].photoUrl string Y URL of a multilingual image
    Max length: 1,000 characters
    i18nDescriptions[] array N Multilingual descriptions of the message bot
    i18nDescriptions[].language string Y Language code
    ○ ko_KR ○ ja_JP ○ zh_CN ○ zh_TW ○ en_US
    i18nDescriptions[].description string Y Multilingual description of the message bot
    Max length: 100 characters

    Request Example

    simple

    
    POST https://apis.worksmobile.com/r/apiid/message/v1/bot
    {
      "name": "echo bot",
      "photoUrl": "https://developers.worksmobile.com/favicon.png",
      "description": "WorksMobile's A.I. conversation enabled bot",
      "managers": ["manager@example.com", "manager2@example.com"]
    }
    
    detail
    
    POST https://apis.worksmobile.com/r/apiid/message/v1/bot
    {
      "name": "echo bot",
      "i18nNames": [{
        "language": "ko_KR",
        "name": "에코봇"
      }, {
        "language": "ja_JP",
        "name": "エコボッ"
      }],
      "photoUrl": "https://developers.worksmobile.com/favicon.png",
      "i18nPhotoUrls": [{
        "language": "ko_KR",
        "photoUrl": "https://developers.worksmobile.com/favicon.png"
      },{
        "language": "ja_JP",
        "photoUrl": "https://developers.worksmobile.com/favicon.png"
      }],
      "description": "WorksMobile's A.I. conversation enabled bot",
      "i18nDescriptions": [{
        "language": "ko_KR",
        "description": "웍스모바일의 A.I 대화가 가능한 봇"
      },{
        "language": "ja_JP",
        "description": "ワークスモバイルのA.I対話が可能なボット"
      }],
      "managers": ["manager@example.com", "manager2@example.com"],
      "submanagers": ["submanager@example.com"],
      "useGroupJoin": true,
      "useDomainScope": false,
      "useCallback": true,
      "callbackUrl": "https://xxx",
      "callbackEvents": ["text", "location", "sticker", "image"]
    }
    

    Response

    It returns HTTP status 200 with a message bot number as a response if successful.

    Property Type Description
    botNo number Message bot number

    Response Example

    
    {
      "botNo": 123
    }
    

    Error Code

    If the API call fails, it returns an error code and message.
    For error codes, refer to Message Bot REST API Error Codes.