SAMA chat server API: Address book
INDEPENDENTLY — ACCESSIBLE — EASILY
Each of us has at least once faced a situation where we wanted to write to an friend from our contact list, but couldn’t find them on the platform. That is why we have developed a logic that will allow you to synchronize your contact list with the existing users of the system.
SAMA Adress book API has 5 methods to solve the above problem:
- ➕
contact_add| Match user - 📋
contact_batch_add| Match users - ♻️
contact_update| Update contact - 📃
contact_list| Get a list of contacts - ❌
contact_delete| Delete a contact
Match user
~ request name: contact_add
When you need to check if there is a user in the system with the data you have in your contacts, send a request ⬆️ with the contact object:
{
request: {
contact_add: {
first_name: "Oleksandr",
last_name: "Range",
company: "Global",
email: [
{ type: "work", value: "..." },
{ type: "home", value: "..." },
...
],
phone: [
{ type: "work", value: "..." },
{ type: "home", value: "..." },
...
]
},
id: "add_request"
}
}And then the system will look through the existing users in the system by key fields, and if a match is found, the contact will be assigned the matched user_id field with the matchin user.
You can see how this will be reproduced in the response ⬇️:
{
response: {
contact: {
_id: "63480e68f4794709f802a2fa",
first_name: "Oleksandr",
last_name: "Range",
company: "Global",
email: [
{ type: "work", value: "...", matched_user_id: "uId5" },
{ type: "home", value: "..." },
...
],
phone: [
{ type: "work", value: "..." },
{ type: "home", value: "...", matched_user_id: "uId7" },
...
],
updated_at: "2023-07-04T07:23:53.308Z",
created_at: "2023-07-04T07:23:53.308Z"
},
id: "add_request"
}
}❕ As you can see, searching for user matches is not limited to just one user.
Match users
~ request name: contact_batch_add
The following method will be useful for those who have a 📋 list of contacts that need to be checked for matches. So send the entire list and the search for users will be reproduced in a similar way as in the first method:
The request ⬆️ will look like this:
{
request: {
contacts: [
{
first_name: "Rio",
last_name: "Hale",
company: "NotGlobal",
email: [ { type: "work", value: "..." } ],
phone: [ { type: "home", value: "..." } ]
},
{
first_name: "Mark",
last_name: "Velazquez",
company: "MaybeGlobal",
email: [ { type: "work", value: "..." } ],
phone: [ { type: "home", value: "..." } ]
},
...
],
id: "bath_add_requesst"
}
}And as a response ⬇️, you will receive your list, but with the user ID, if it was found:
{
response: {
id: "5",
contacts: [
{
_id: "63480e68f4794709f802a2fa",
first_name: "Rio",
last_name: "Hale",
company: "NotGlobal",
email: [ { type: "home", value: "..." } ],
phone: [
{ type: "home", value: "...", matched_user_id: "uId7" }
],
updated_at: "2023-07-04T07:23:53.308Z",
created_at: "2023-07-04T07:23:53.308Z"
},
{
_id: "63480e68f4794709f802a2fy",
first_name: "Mark",
last_name: "Velazquez",
company: "MaybeGlobal",
email: [ { type: "home", value: "..." } ],
phone: [
{ type: "home", value: "...", matched_user_id: "uId6" }
],
updated_at: "2023-07-04T07:23:53.308Z",
created_at: "2023-07-04T07:23:53.308Z"
}
]
}
}Update contact
~ request name: contact_update
If you have already had a contact, but need to check again for matches in the database, then this request ⬆️ is for you:
{
request: {
contact_update: {
id: "63480e68f4794709f802a2fa",
first_name: "Johnny",
last_name: "Donnelly",
company: "Global",
email: [
{ type: "work", value: "..." },
{ type: "home", value: "..." },
...
],
phone: [
{ type: "work", value: "..." },
{ type: "home", value: "..." },
...
]
},
id: "update_request"
}
}Receive a response ⬇️ with an updated record:
{
response: {
id: "14",
contact: {
_id: "63480e68f4794709f802a2fa",
first_name: "Johnny",
last_name: "Donnelly",
company: "Global",
email: [
{ type: "work", value: "...", matched_user_id: "uId5" },
{ type: "home", value: "..." },
...
],
phone: [
{ type: "work", value: "..." },
{ type: "home", value: "...", matched_user_id: "uId7" },
...
],
updated_at: "2023-07-04T07:23:53.308Z",
created_at: "2023-07-04T07:23:53.308Z"
}
}
}Get a list of contacts
~ request name: contact_list
The next, no less useful method that will allow you to get a list of contacts:
{
request: {
contact_list: {
updated_at: "2023-07-04T07:23:53.308Z",
limit: 56,
},
id: "list_request"
}
}And get a response ⬇️ from users just as quickly:
{
response: {
contacts: [
{
_id: "63480e68f4794709f802a2fa",
first_name: "Orlando",
last_name: "Brady",
company: "Global",
email: [ { type: "home", value: "..." } ],
phone: [
{ type: "home", value: "...", matched_user_id: "uId7" }
],
updated_at: "2023-07-04T07:23:53.308Z",
created_at: "2023-07-04T07:23:53.308Z"
},
{
_id: "63480e68f4794709f802a2fy",
first_name: "Arun",
last_name: "Curtis",
company: MaybeGlobal",
email: [ { type: "home", value: "..." } ],
phone: [
{ type: "home", value: "...", matched_user_id: "uId6" }
],
updated_at: "2023-07-04T07:23:53.308Z",
created_at: "2023-07-04T07:23:53.308Z"
},
...
],
id: "list_request"
}
}Delete a contact
~ request name: contact_delete
If you need to delete a contact from your contacts list, send the following request ⬆️ with the contact ID:
{
request: {
contact_delete: {
id: "63480e68f4794709f802a2fa"
},
id: "delete_request"
}
}And get confirmation ⬇️ of your request:
{
response: {
success: true,
id: "delete_request"
}
}Conclusion
If you need to easily and conveniently check for matches 👤 with users in your system, then use SAMA chat server APIs and your goal will be achieved 🏆!
👀 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!
