MessagesAPI Documentation

MessagesAPI is a JavaScript library for interacting with various APIs, including Messages, Conversations, Applications, and conv.php.

Setup

Include the messages.js file in your HTML:

<script src="messages.js"></script>

Set your API key after the script is loaded. The MessagesAPI object is globally accessible as window.Messages:

<script>
  window.Messages.setApiKey('YOUR_API_KEY_HERE');
</script>

APIs

1. Messages API

Methods for managing messages:

• window.Messages.getMessages(queryParams): Fetches messages based on query parameters.
• window.Messages.createMessage(body): Creates a new message. The body should include:
  • conversationId: ID of the conversation.
  • userId: ID of the user sending the message.
  • toUserId: ID of the recipient user.
  • type: Type of the message.
  • typeId: Type ID of the message.
  • metadata: Additional metadata for the message.
  • text: The message text.
• window.Messages.updateMessage(id, body): Updates an existing message. The body should include:
  • type: Type of the message.
  • typeId: Type ID of the message.
  • metadata: Additional metadata for the message.
  • text: The updated message text.
• window.Messages.deleteMessage(id): Deletes a message by ID.

2. Conversations API

Methods for managing conversations:

• window.Messages.getConversations(queryParams): Fetches conversations based on query parameters.
• window.Messages.createConversation(body): Creates a new conversation. The body should include:
  • applicationId: ID of the application.
  • type: Type of the conversation.
  • typeId: Type ID of the conversation.
  • metadata: Additional metadata for the conversation.
  • status: Status of the conversation.
• window.Messages.updateConversation(id, body): Updates an existing conversation. The body should include:
  • type: Type of the conversation.
  • typeId: Type ID of the conversation.
  • metadata: Additional metadata for the conversation.
• window.Messages.deleteConversation(id): Deletes a conversation by ID.

3. Applications API

Methods for managing applications:

• window.Messages.getApplications(queryParams): Fetches applications based on query parameters.
• window.Messages.createApplication(body): Creates a new application. The body should include:
  • name: Name of the application.
  • apiKey: API key for the application.
  • ownerUserId: ID of the owner user.
• window.Messages.updateApplication(id, body): Updates an existing application. The body should include:
  • name: Name of the application.
  • apiKey: API key for the application.
  • ownerUserId: ID of the owner user.
• window.Messages.deleteApplication(id): Deletes an application by ID.

4. conv.php API

Methods for retrieving conversations for a specific user:

• window.Messages.getConv(userId): Fetches conversations for a specific user by their ID.

5. Start API

Methods for starting a new conversation with the first message:

• window.Messages.startConversation(body): Starts a new conversation with the first message. The body should include:
  • type: Type of the conversation.
  • typeId: Type ID of the conversation.
  • metadata: Additional metadata for the conversation.
  • status: Status of the conversation.
  • userId: ID of the user sending the first message.
  • toUserId: ID of the recipient user.
  • text: The first message text.

6. Reads API

Methods for marking messages as read:

• window.Messages.markMessagesRead(userId, conversationId, lastReadMessageId, recordId = null): Marks messages as read. If recordId is provided, it updates the existing record; otherwise, it creates a new record.

TypeScript Type Declarations

Below are the TypeScript interfaces for the API responses:

// Message API Response
interface Message {
  id: number;
  conversationId: number;
  userId: number;
  toUserId: number;
  type: string;
  typeId: number;
  metadata: Record<string, any>;
  text: string;
  createdAt: string;
  updatedAt: string;
}

// Conversation API Response
interface Conversation {
  id: number;
  applicationId: number;
  type: string;
  typeId: number;
  metadata: Record<string, any>;
  status: string;
  createdAt: string;
  updatedAt: string;
  messages: Message[]; // Associated messages
}

// Application API Response
interface Application {
  id: number;
  name: string;
  apiKey: string;
  ownerUserId: number;
  createdAt: string;
  updatedAt: string;
}

// Start API Response
interface StartResponse {
  conversation: Conversation;
  message: Message;
}

// General API Error Response
interface ApiError {
  error: string;
  message: string;
}