How to Use the Messages API to Streamline User Authentication with Message Tokens
Our Messages API provides a robust solution for real estate agents to communicate seamlessly with clients, allowing them to send personalized messages related to new listings, price changes, or sales updates. This guide will explain how to use the API to send messages, track interactions, and implement magic links for secure, password-less authentication on your website.
The Messages API enables you to:
Send messages directly to clients from agents.
Automate notifications for new listings, price changes, or sales events.
Embed tokens in clickable links to support secure and password-less login for clients (magic links).
Each message can include custom content such as listings, searches, messages, links, or images, enhancing client engagement with timely, relevant information.
When a message is sent, each clickable item within the message contains a unique identifier, called a token. The token is in UUID format, providing a secure way to identify and authorize the client. For example:
?token=550e8400-e29b-41d4-a716-446655440000
This token is appended as a query string parameter when the client clicks on a link within the message, which directs them back to your website.
To use the token for identifying the client:
Make a GET request to our Messages API with the token:
GET https://api.repliers.io/messages?token=550e8400-e29b-41d4-a716-446655440000
If the token is valid, the API response will return details about the message and the associated client. Here’s an example of the response structure:
You can then use this information to verify the client’s identity based on the token, establishing a secure and convenient login experience.
Since the message token is unique and embedded in each clickable link, it can be used to allow password-less login (also known as magic links). Here’s how this works:
Token Verification: Upon clicking, the client is redirected to your website with the token as a query string.
Client Identification: Use the GET /messages API call with the token to retrieve the client’s details.
Authorization: Once validated, authorize the client’s session on your website. Since the token is specific to the client, only they can access it by clicking the link.
Session Establishment: This process provides a secure and password-less login experience, allowing you to log in the client without the need for a traditional password.
To implement magic links:
An agent sends a message containing a clickable link to a client.
The client clicks the link and is directed to your website with the appended token (?token=550e8400-e29b-41d4-a716-446655440000).
Your website processes the token by calling:
GET https://api.repliers.io/messages?token=550e8400-e29b-41d4-a716-446655440000
If the response validates the token, the client’s session is authorized on your website.
Token Format: The token is always in UUID format and remains unique for each message.
Security: The use of tokens ensures that only the intended recipient can click and log in via the magic link.
Customization: Each message can contain links, images, or listings to personalize the communication.
This setup streamlines client interactions, ensuring a secure, efficient, and user-friendly experience. Integrate our Messages API to enhance engagement and simplify client authentication on your platform.
Before implementing passwordless login using message tokens, it’s essential to check with your MLS provider to confirm that this approach aligns with their security and data usage policies. Some MLS organizations have specific requirements regarding user authentication methods, data access, and privacy standards, which may impact the use of passwordless login solutions. Ensuring compliance not only protects your clients’ data but also maintains the integrity of your MLS integration. Always verify these guidelines with your MLS to avoid potential issues and to fully utilize the features of the Messages API within permitted parameters.
Overview of Messages API
The Messages API enables you to:
Send messages directly to clients from agents.
Automate notifications for new listings, price changes, or sales events.
Embed tokens in clickable links to support secure and password-less login for clients (magic links).
Each message can include custom content such as listings, searches, messages, links, or images, enhancing client engagement with timely, relevant information.
Message Tokens and Query Parameters
When a message is sent, each clickable item within the message contains a unique identifier, called a token. The token is in UUID format, providing a secure way to identify and authorize the client. For example:
?token=550e8400-e29b-41d4-a716-446655440000
This token is appended as a query string parameter when the client clicks on a link within the message, which directs them back to your website.
Identifying the Client Using Tokens
To use the token for identifying the client:
Make a GET request to our Messages API with the token:
GET https://api.repliers.io/messages?token=550e8400-e29b-41d4-a716-446655440000
If the token is valid, the API response will return details about the message and the associated client. Here’s an example of the response structure:
{
"messages": [
{
"messageId": 111111111,
"agentId": 888888,
"sender": "agent",
"source": "bot",
"clientId": 666666,
"token": "b11238d2-8a22-4d7e-87cc-f73car456ee22",
"content": {
"listings": [],
"searches": [],
"message": "Hi, how are you? Here's a listing you might like.",
"subject": null,
"links": [
"https://www.domain.com/listings/C9231328"
],
"pictures": []
},
"delivery": {
"scheduleDateTime": null,
"sentDateTime": "2024-08-01T00:21:26.000Z",
"status": "sent"
}
}
]
}You can then use this information to verify the client’s identity based on the token, establishing a secure and convenient login experience.
Using Tokens for Password-less Authentication (Magic Links)
Since the message token is unique and embedded in each clickable link, it can be used to allow password-less login (also known as magic links). Here’s how this works:
Token Verification: Upon clicking, the client is redirected to your website with the token as a query string.
Client Identification: Use the GET /messages API call with the token to retrieve the client’s details.
Authorization: Once validated, authorize the client’s session on your website. Since the token is specific to the client, only they can access it by clicking the link.
Session Establishment: This process provides a secure and password-less login experience, allowing you to log in the client without the need for a traditional password.
Practical Example
To implement magic links:
An agent sends a message containing a clickable link to a client.
The client clicks the link and is directed to your website with the appended token (?token=550e8400-e29b-41d4-a716-446655440000).
Your website processes the token by calling:
GET https://api.repliers.io/messages?token=550e8400-e29b-41d4-a716-446655440000
If the response validates the token, the client’s session is authorized on your website.
Additional Information
Token Format: The token is always in UUID format and remains unique for each message.
Security: The use of tokens ensures that only the intended recipient can click and log in via the magic link.
Customization: Each message can contain links, images, or listings to personalize the communication.
This setup streamlines client interactions, ensuring a secure, efficient, and user-friendly experience. Integrate our Messages API to enhance engagement and simplify client authentication on your platform.
Check With Your MLS
Before implementing passwordless login using message tokens, it’s essential to check with your MLS provider to confirm that this approach aligns with their security and data usage policies. Some MLS organizations have specific requirements regarding user authentication methods, data access, and privacy standards, which may impact the use of passwordless login solutions. Ensuring compliance not only protects your clients’ data but also maintains the integrity of your MLS integration. Always verify these guidelines with your MLS to avoid potential issues and to fully utilize the features of the Messages API within permitted parameters.
Updated on: 29/11/2024
Thank you!