Open in app

Sign in

Write

Sign in

SAMA chat server API: Messages

SIMPLE — AFFORDABLE — REAL

Oleksandr Chabaniuk
SAMA communications

--

Based on ease of use, and with easy-to-understand documentation and articles on how to set up and use our APIs, we want to show that it is REAL to build communication into your application .

Boxes with text? Yes, that’s what you’ll see all the time.And only 5 methods will allow you to improve and speed up the creation and delivery of these “boxes” 📦.

In our SAMA Messages API, we have described all 5 methods, plus one more method that will facilitate communication between users:

  • 📩 message | Create a message
  • 📝message_edit | Edit message content
  • 📃message_list | Get a list of chat messages
  • ☑ message_read | Mark message as read
  • ❌message_delete | Delete a message
  • ✒️typing | * This will help to update your ‘typing’ status

Create a message

~ request name: message

Great, let’s take a look at what the object of the Message is.

This is what your message creation request ⬆️ looks like:

{
  message: {
    id: "61280e68f4794709f652a2bf",
    body: "Hey, how's it going?",
    cid: "63480e68f4794709f802a2fa",
    x: {
      param1: "value",
      param2: "value"
    },
    attachments: [
      { name: "file_1", size: 240, content_type: "type" },
      { name: "file_2", size: 126, content_type: "type" }
    ],
  }
}

Now let’s look at the fields we have available:

  • 🆔id | Identify your message so that it is not lost until it is assigned a static id in the database
  • 🔤body | Pass the text content here (or not, if you have files 😶)
  • 📬cid | Attach the ID of the current conversation
  • 🔧x (like eXtension) | If you need to pass specific parameters, use this field
  • 🧷attachments | Pass an array of files, if necessary (up to 🔟)

In response ⬇️, the server will send you the message ID you specified and the static message ID from the database so that you can update it locally:

{
  ask: {
    mid: "61280e68f4794709f652a2bf",
    server_mid: "63480e68f4794709f802a2fa",
    t: 15673838833
  }
}

❕After receiving this message, you can safely set the status to “sent”.

Okay, we sent the message to the server, saved it, but what about other users? How will they receive it?

This is a good question, and we have an answer. Let’s imagine that we have two users who are offline and online, respectively.

So, let’s consider the case when the opponent(s) is offline, so the message object will not be useful to them, so let’s notify them that they have a new message. Let’s send him a push message 🔔 with the following content:

{
  title: "Oliv3r1" / "Oliv3r1 | GroupConversation",
  body: "Hey, how's it going?",
  cid: "63480e68f4794709f802a2fa",
  firstAttachmentUrl: "..."
}

Great, now let’s take a look at the object that online 💡 users will receive.

{
  message: {
    _id: "63480e68f4794709f802a2fa",
    t: 15673838833,
    from: "634ec51c0b65918393dca5bf",
    body: "Hey, how's it going?",
    cid: "63480e68f4794709f802a2fa",
    x: {
      param1: "value",
      param2: "value"
    },
    attachments: [
      { file_id: "541v2a_file_1", file_name: "fil_1" },
      { file_id: "983z7e_file_2", file_name: "fil_1" }
    ],
    created_at: "2023-07-04T07:23:53.308Z",
  }
}

Fields you should pay attention to:

  • 🕐 t | Time when the message was created
  • 👤 from | ID of the user who sent this message

Typing status

~ request name: typing

Sometimes we write a message too long or rewrite it several times. Can we show this to other users so they know we’re not ignoring them?

Yeah, of course. You can send messages with the appropriate status about your activity (all users will receive the same notification):

{
  typing: {
    id: "62180e68f4794709f802a3vb",
    t: 15673838833,
    type: "start/stop",
    cid: "63480e68f4794709f802a2fa"
  }
}

Edit message content

~ request name: message_edit

It happens that you put a comma in the wrong place or missed a button with a letter, can we do something about it?

Of course, you can actually edit the text of your message. To do this, you need to send such a request ⬆️:

{
  request: {
    message_edit: {
      id: "63077ad836b78c3d82af0812",
      body: "Maybe you've already tried our API?)"
    },
    id: "edit_request"
  }
}

And in response ⬇️, you will receive a confirmation of the successful changes:

{ 
  response: { 
    success: true,
    id: "edit_request"
  } 
}

And if you ask about other users again, they will also receive 🔔 a message with updated fields on the message:

{
  message_edit: {
    id: "63077ad836b78c3d82af0812",
    body: "Maybe you've already tried our API?)",
    from: "634ec51c0b65918393dca5bf"
  }
}

* In the future, we plan to implement support for interaction with atachments.

Get a list of chat messages

~ request name: message_list

It would be great to receive a list of messages when you load a chat or enter it for the first time, and since you are already familiar with a similar request in the SAMA Conversations API, all you have to do is specify the parameters (if necessary):

  • 🕐 updated_at | Use gt and lt to specify a time range
  • 🔢 limit | Add a limit to the maximum number of records

And send this request ⬆️:

{
  request: {
    message_list: {
      cid: "63480e68f4794709f802a2fa",
      limit: 27,
      updated_at: {
        gt: "2023-07-04T07:23:53.308Z"
      }
    },
    id: "list_request"
  }
}

In response ⬇️, you will receive a list of messages:

{
  response: {
    messages: [
      {
        _id: "64edc1f2a9d7b47ad3584269",
        body: "Fast!",
        cid: "63480e68f4794709f802a2fa",
        from: "634ec51c0b65918393dca5bf",
        t: 1693303282,
        created_at: "2023-08-29T10:01:22.055Z",
        status: "sent"
      },
      {
        _id: "64ba7dad24c8536eae73ae00",
        body: "Scalable!",
        cid: "63480e68f4794709f802a2fa",
        from: "6479dfa24f8e0c57edf07dd1",
        t: 1689943470,
        created_at: "2023-07-21T12:44:29.778Z"
      },
      {
        _id: "649d8a69905dbd7676ce6fb4",
        body: "",
        cid: "63480e68f4794709f802a2fa",
        attachments: [
          {
          file_id: "1d804b76bb5f8158ac84e088file.png",
          file_name: "file.png"
          }
        ],
        from: "6479dfa24f8e0c57edf07dd1",
        t: 1688046185,
        created_at: "2023-06-29T13:43:05.227Z"
      },
      {
        _id: "649d89e8905dbd7676ce6fab",
        body: "Easy!",
        cid: "63480e68f4794709f802a2fa",
        from: "6479dfa24f8e0c57edf07dd1",
        t: 1688046057,
        created_at: "2023-06-29T13:40:56.503Z"
      },
      ...
    ],
    id: "list_request"
  }
}

Mark message as read

~ request name: message_read

One of the most useful functions is to notify your opponent about the message you read. It’s a must! Otherwise, it will be like a one-way game 🏈.

Group the necessary messages into an array 📃 and send them ⬆️:

{
  request: {
    message_read: {
      cid: "63480e68f4794709f802a2fa",
      ids: [
        63480e68f4794709f802a2fa,
        63077ad836b78c3d82af0866,
        ...
      ]
    },
    id: "read_request"
  }
}

And all participants who are currently online 💡 will receive the same message ⬇️:

{
  message_read: {
    cid: "63480e68f4794709f802a2fa",
    ids: [
      63480e68f4794709f802a2fa,
      63077ad836b78c3d82af0866,
      ...
    ],
    from: "634ec51c0b65918393dca5bf"
  }
}

And you will receive a confirmation of the success of the request:

{ 
  response: { 
    success: true,
    id: "edit_request"
  } 
}

Delete a message

~ request name: message_delete

And the last request for today will be to delete the message. It’s simple:

Is a notification bothering you? Then delete it! 😉

This also works in a similar scenario📋: send a request ⬆️ to the server:

{
  request: {
    message_delete: {
      cid: "63480e68f4794709f802a2fa",
      ids: ["63077ad836b78c3d82af0812", "63077ad836b78c3d82af0813"],
      type: "myself" | "all"
    },
    id: "delete_request"
  }
}
  • type | You can delete for yourself or for all

Get a confirmation ⬇️ from the server:

{ 
  response: { 
    success: true,
    id: "delete_request"
  } 
}

Finally, we will inform 🔔 everyone in the chat about it:

{
  message_delete: {
    cid: "63077ad836b78c3d82af0812",
    ids: [
      "63077ad836b78c3d82af0812", 
      "63077ad836b78c3d82af0813", 
      ...
    ],
    type: "all",
    from: "634ec51c0b65918393dca5bf"
  }
}

❕Now try it yourself ! 👇🏼

Conclusion

Use this and other sets of our SAMA chat server APIs to reduce the amount of time 🕐 you spend waiting for messages and use it to create ideas ✨ for improving your product.

👀 Check out more posts on our page for fantastic improvements to your app!

Try SAMA 👇🏼

To run SAMA server locally — follow https://github.com/SAMA-Communications/sama-server. Frontend app is available at https://github.com/SAMA-Communications/sama-client.

Discover, enjoy, and all feedback is welcome. We will be thankful a lot for every GitHub star, issue, or comment!

SAMA-Communications

SAMA-Communications has 5 repositories available. Follow their code on GitHub.

github.com

--

--

Oleksandr Chabaniuk
SAMA communications

Written by Oleksandr Chabaniuk

12 Followers
Editor for