Messages

Users

Represents a user/customer/player interacting with SAGA.

GET /users/:user_id/messages/

Returns a time sorted list of messages sent to or from the user with the given user_id.

Message data structure

• sender_id - the id of the sender
• sender_type - the type of the sender, either User or Bot
• user_ids - the ids of the users participating in the message, if sender_type === User, will contain sender_id
• bot_ids - the ids of the bots participating in the message, if sender_type === Bot, will contain sender_id
• body - message body
• context - additional key value data
• source_creator - the creator of the message
  • type - either 'jobs', 'scripts', 'rest' or 'socket'
  • id - the id of the script or job if that is the type
• runnable_call_id - the runnable_call_id associated with the script or job
• attachments - contains url,mime_type tuples

[
   {
      "sender_id":"60bf527fdbd52e0069edcade",
      "sender_type": "Bot",
      "bot_ids": ["60bf527fdbd52e0069edcade"],
      "user_ids": ["60ca6018959192003229064f"],
      "body":"You're welcome.",
      "source_creator":{
         "id":"60bfdc9d62c31d0034122f8c",
         "type":"scripts"
      },
      "runnable_call_id":"60ca615a6fce1a02f478da41",
      "attachments":[
        {
          "url": "http://www.images.com/image.png",
          "mime_type":"image/png"
        }         
      ],
      "createdAt":"2021-06-16T20:38:51.565Z"
   },
   {
      "sender_id":"60bf527fdbd52e0069edcade",
      "sender_type": "User",
      "user_ids": ["60bf527fdbd52e0069edcade"],
      "bot_ids": ["60ca6018959192003229063c"],
      "body":"welcome",
      "context":{
         "volume": 6
      },
      "source_creator":{
         "id":"60bf50ce50954100682ecf0e",
         "type":"scripts"
      },
      "runnable_call_id":"60ca615a959192003229067e",
      "attachments":[],
      "createdAt":"2021-06-16T20:38:50.882Z"
   }
]

POST /users/:user_id/messages/

Creates a new message sent by user_id.

POST

{
  "bot_ids": ["60ca6018959192003229063c"],
  "body":"You're welcome.",
  "context":{
     "volume": 2     
  }
}

GET /users/:user_id/messages/:message_id

Get the message with the given message_id

{
  "sender_id":"60bf527fdbd52e0069edcade",
  "sender_type": "Bot",
  "bot_ids": ["60bf527fdbd52e0069edcade"],
  "user_ids": ["60ca6018959192003229064f"],
  "body":"You're welcome.",
  "source_creator":{
    "id":"60bfdc9d62c31d0034122f8c",
    "type":"scripts"
  },
  "runnable_call_id":"60ca615a6fce1a02f478da41",
  "attachments":[
    {
      "url": "http://www.images.com/image.png",
      "mime_type":"image/png"
    }
  ],
  "createdAt":"2021-06-16T20:38:51.565Z"
}

GET /users/:user_id/messages/around/:message_id

Returns a list of messages around the message with the message_id, radius is 5 before and after the given message.

DELETE /users/:user_id/messages/:message_id

Deletes the message with the given message_id.

GET /users/:user_id/messages/with/bot/:bot_id

Returns a time sorted list of messages between the user with the given user_id and the bot with the given bot_id.

GET /users/:user_id/messages/with/user/:other_user_id

Returns a time sorted list of messages between the user with the given user_id and the user with the given other_user_id.

DELETE /users/:user_id/messages/with/bot/:bot_id

Removes user_id from all messages sent by bot_id, and removes bot_id from all messages sent by user_id. Does not actually delete the messages.

DELETE /users/:user_id/messages/with/user/:other_user_id

Removes user_id from all messages sent by other_user_id, and removes other_user_id from all messages sent by user_id. Does not actually delete the messages.

GET /users/:user_id/threads/

Required parameters:

• group_by:
  • Group messages by unique user_ids and bot_ids: ['user_ids', 'bot_ids']
  • Group messages by unique context.quest: ['context.quest']
  • Valid fields:
    • sender_id, sender_type, user_ids, bot_ids, context.<*>

Returns a list containing all the distinct message groupings for the user. Each entry contains:

• sender_id - the id of the sender
• sender_type - the type of the sender, either User or Bot
• sender - contains the name, displayname, or username
• user_ids - the ids of the users participating in the message, if sender_type === User, will contain sender_id
• users - contains the users in the message, populated with usernames and displaynames
• bot_ids - the ids of the bots participating in the message, if sender_type === Bot, will contain sender_id
• bots -- contains the bots in the message, populated with names
• body - message body
• context - additional key value data
• source_creator - the creator of the message
  • type - either 'jobs', 'scripts', 'rest' or 'socket'
  • id - the id of the script or job if that is the type
• runnable_call_id - the runnable_call_id associated with the script or job
• attachments - contains url,mime_type tuples
• count - the number of messages in this group

[
  {
    "_id": "64f380fcfd82d035f7172c98",
    "sender_id": "642c01e956ff63e77f745903",
    "sender_type": "Bot",
    "sender": {
      "_id": "642c01e956ff63e77f745903",
      "name": "QUESTENGINE_ENTITY_LSutsB"
    },
    "user_ids": [
      "64f38067d27f60a79f57fd92"
    ],
    "users": [
      {
        "_id": "64f38067d27f60a79f57fd92",
        "username": "guest_20230902181446_12103"
      }
    ],
    "bot_ids": [
      "642c01e956ff63e77f745903"
    ],
    "bots": [
      {
        "_id": "642c01e956ff63e77f745903",
        "name": "QUESTENGINE_ENTITY_LSutsB"
      }
    ],
    "body": "Hi, sorry if I seem distracted, I'm on a search for truth!",
    "attachments": [],
    "createdAt": "2023-09-02T18:37:48.152Z",
    "count": 2
  },
  {
    "_id": "64f380e3fd82d035f7172c70",
    "sender_id": "642c0183ed4d5ebf5dc1c138",
    "sender_type": "Bot",
    "sender": {
      "_id": "642c0183ed4d5ebf5dc1c138",
      "name": "QUESTENGINE_ENTITY_7hKruE"
    },
    "user_ids": [
      "64f38067d27f60a79f57fd92"
    ],
    "users": [
      {
        "_id": "64f38067d27f60a79f57fd92",
        "username": "guest_20230902181446_12103"
      }
    ],
    "bot_ids": [
      "642c0183ed4d5ebf5dc1c138"
    ],
    "bots": [
      {
        "_id": "642c0183ed4d5ebf5dc1c138",
        "name": "QUESTENGINE_ENTITY_7hKruE"
      }
    ],
    "body": "I'll be here when you're done, good luck!",
    "attachments": [],
    "createdAt": "2023-09-02T18:37:23.494Z",
    "count": 15
  }
]

Bots

Simple object to represent non-users such as chatbots or autonomous agents.

GET /bots/:bot_id/messages/

Returns a time sorted list of messages sent to or from the bot with the given bot_id.

Message data structure

• sender_id - the id of the sender
• sender_type - the type of the sender, either Bot or User
• bot_ids - the ids of the bots participating in the message, if sender_type === Bot, will contain sender_id
• user_ids - the ids of the users participating in the message, if sender_type === User, will contain sender_id
• body - message body
• context - additional key value data
• source_creator - the creator of the message
  • type - either 'jobs', 'scripts', 'rest' or 'socket'
  • id - the id of the script or job if that is the type
• runnable_call_id - the runnable_call_id associated with the script or job
• attachments - contains url,mime_type tuples

[
   {
      "sender_id":"60bf527fdbd52e0069edcade",
      "sender_type": "User",
      "user_ids": ["60bf527fdbd52e0069edcade"],
      "bot_ids": ["60ca6018959192003229064f"],
      "body":"You're welcome.",
      "source_creator":{
         "id":"60bfdc9d62c31d0034122f8c",
         "type":"scripts"
      },
      "runnable_call_id":"60ca615a6fce1a02f478da41",
      "attachments":[
        {
          "url": "http://www.images.com/image.png",
          "mime_type":"image/png"
        }         
      ],
      "createdAt":"2021-06-16T20:38:51.565Z"
   },
   {
      "sender_id":"60bf527fdbd52e0069edcade",
      "sender_type": "Bot",
      "bot_ids": ["60bf527fdbd52e0069edcade"],
      "user_ids": ["60ca6018959192003229063c"],
      "body":"welcome",
      "context":{
         "volume": 6
      },
      "source_creator":{
         "id":"60bf50ce50954100682ecf0e",
         "type":"scripts"
      },
      "runnable_call_id":"60ca615a959192003229067e",
      "attachments":[],
      "createdAt":"2021-06-16T20:38:50.882Z"
   }
]

POST /bots/:bot_id/messages/

Creates a new message sent by bot_id.

POST

{
  "user_ids": ["60ca6018959192003229063c"],
  "body":"You're welcome.",
  "context":{
     "volume": 2     
  }
}

GET /bots/:bot_id/messages/:message_id

Get the message with the given message_id

{
  "sender_id":"60bf527fdbd52e0069edcade",
  "sender_type": "User",
  "user_ids": ["60bf527fdbd52e0069edcade"],
  "bot_ids": ["60ca6018959192003229064f"],
  "body":"You're welcome.",
  "source_creator":{
    "id":"60bfdc9d62c31d0034122f8c",
    "type":"scripts"
  },
  "runnable_call_id":"60ca615a6fce1a02f478da41",
  "attachments":[
    {
      "url": "http://www.images.com/image.png",
      "mime_type":"image/png"
    }
  ],
  "createdAt":"2021-06-16T20:38:51.565Z"
}

GET /bots/:bot_id/messages/around/:message_id

Returns a list of messages around the message with the message_id, radius is 5 before and after the given message.

DELETE /bots/:bot_id/messages/:message_id

Deletes the message with the given message_id.

GET /bots/:bot_id/messages/with/user/:user_id

Returns a time sorted list of messages between the bot with the given bot_id and the user with the given user_id.

GET /bots/:bot_id/messages/with/bot/:other_bot_id

Returns a time sorted list of messages between the bot with the given bot_id and the bot with the given other_bot_id.

DELETE /bots/:bot_id/messages/with/user/:user_id

Removes bot_id from all messages sent by user_id, and removes user_id from all messages sent by bot_id. Does not actually delete the messages.

DELETE /bots/:bot_id/messages/with/bot/:other_bot_id

Removes bot_id from all messages sent by other_bot_id, and removes other_bot_id from all messages sent by bot_id. Does not actually delete the messages.

GET /bots/:bot_id/threads/

Required parameters:

• group_by:
  • Group messages by unique bot_ids and user_ids: ['bot_ids', 'user_ids']
  • Group messages by unique context.quest: ['context.quest']
  • Valid fields:
    • sender_id, sender_type, bot_ids, user_ids, context.<*>

Returns a list containing all the distinct message groupings for the bot. Each entry contains:

• sender_id - the id of the sender
• sender_type - the type of the sender, either Bot or User
• sender - contains the name, displayname, or botname
• bot_ids - the ids of the bots participating in the message, if sender_type === Bot, will contain sender_id
• bots - contains the bots in the message, populated with botnames and displaynames
• user_ids - the ids of the users participating in the message, if sender_type === User, will contain sender_id
• users -- contains the users in the message, populated with names
• body - message body
• context - additional key value data
• source_creator - the creator of the message
  • type - either 'jobs', 'scripts', 'rest' or 'socket'
  • id - the id of the script or job if that is the type
• runnable_call_id - the runnable_call_id associated with the script or job
• attachments - contains url,mime_type tuples
• count - the number of messages in this group

[
  {
    "_id": "64f380fcfd82d035f7172c98",
    "sender_id": "642c01e956ff63e77f745903",
    "sender_type": "User",
    "sender": {
      "_id": "642c01e956ff63e77f745903",
      "name": "QUESTENGINE_ENTITY_LSutsB"
    },
    "bot_ids": [
      "64f38067d27f60a79f57fd92"
    ],
    "bots": [
      {
        "_id": "64f38067d27f60a79f57fd92",
        "botname": "guest_20230902181446_12103"
      }
    ],
    "user_ids": [
      "642c01e956ff63e77f745903"
    ],
    "users": [
      {
        "_id": "642c01e956ff63e77f745903",
        "name": "QUESTENGINE_ENTITY_LSutsB"
      }
    ],
    "body": "Hi, sorry if I seem distracted, I'm on a search for truth!",
    "attachments": [],
    "createdAt": "2023-09-02T18:37:48.152Z",
    "count": 2
  },
  {
    "_id": "64f380e3fd82d035f7172c70",
    "sender_id": "642c0183ed4d5ebf5dc1c138",
    "sender_type": "User",
    "sender": {
      "_id": "642c0183ed4d5ebf5dc1c138",
      "name": "QUESTENGINE_ENTITY_7hKruE"
    },
    "bot_ids": [
      "64f38067d27f60a79f57fd92"
    ],
    "bots": [
      {
        "_id": "64f38067d27f60a79f57fd92",
        "botname": "guest_20230902181446_12103"
      }
    ],
    "user_ids": [
      "642c0183ed4d5ebf5dc1c138"
    ],
    "users": [
      {
        "_id": "642c0183ed4d5ebf5dc1c138",
        "name": "QUESTENGINE_ENTITY_7hKruE"
      }
    ],
    "body": "I'll be here when you're done, good luck!",
    "attachments": [],
    "createdAt": "2023-09-02T18:37:23.494Z",
    "count": 15
  }
]