Chat System
API

Chat API

Introduction

ROQ's Chat solution can also be used programmatically using GraphQL or our SDKs. While the primary use cases are taken care of using the UI components, the GraphQL API may be used to achieve custom functionality.

Mutations

createConversation()

ℹ️

This endpoint is only available from the server side of your application.

You can use this endpoint to create a new chat programmatically from your server-side code. The API documentation for this method is here (opens in a new tab).

roq.asUser("4c94b763-9021-499f-8ea3-b01adcdafe57").createConversation({
    conversation: {
        title: "ROQ Hackathon planning",
        ownerId: "4c94b763-9021-499f-8ea3-b01adcdafe57",
        memberIds: [
            "4c94b763-9021-499f-8ea3-b01adcdafe57",
            "7c15cbe7-21f1-4ff7-b742-ec8604682772",
            "cd05a61f-07ca-47e7-abc2-6f0ed9ab645d",
        ],
        isGroup: true,
        tags: ["hackathon"],
    },
});
ParameterTypeDescription
conversation: archivedBoolean?Is the conversation archived or not
conversation:isGroupBoolean?Usually set to true when you have three or more participants or when you need to have a named title for a conversation between 2 participants
conversation:memberIdsstring[]!An array of userIds for participants of the conversation
conversation:ownerIdstring!The userId of the owner - i.e. usually the creator who has permission to archive the conversation
conversation:tagsstring[]?An array of strings. These may be used to filter conversations on the UI Components
conversation:titlestring!The title of the conversation, shown at the top of the chat window

deleteConversation()

Delete a conversation for a specific ID. The API documentation for the deleteConversation() is here (opens in a new tab).

roqClient.asUser("4c94b763-9021-499f-8ea3-b01adcdafe57").deleteConversation({
    id: "7c15cbe7-21f1-4ff7-b742-ec8604682772"
});
ParameterTypeDescription
iduuidConversation ID

assignTagsToConversation()

Assign tags to an existing conversation. These tags can be used to filter conversations on the UI components. Please check the API documentation for assignTagsToConversation() here (opens in a new tab).

roqClient.asUser("7c15cbe7-21f1-4ff7-b742-ec8604682772").assignTagsToConversation({
    conversationId: "7c15cbe7-21f1-4ff7-b742-ec8604682772",
    tags: ["hackathon", "hiring"]
});
ParameterTypeDescription
conversationIduuidThe conversation ID
tagsarrayArray of tags to be assigned to the conversation

unassignTagsFromConversation()

Remove tags from a conversation. The API documentation is here (opens in a new tab).

roqClient.asUser("7c15cbe7-21f1-4ff7-b742-ec8604682772").unassignTagsFromConversation({
    conversationId: "7c15cbe7-21f1-4ff7-b742-ec8604682772",
    tags: ["hackathon", "hiring"]
});
ParameterTypeDescription
conversationIduuidThe conversation ID
tagsarrayArray of tags to be unassigned to the conversation

createMessage()

Send a message to a conversation. The API documentation for createMessage() is here (opens in a new tab).

roqClient.asUser("7c15cbe7-21f1-4ff7-b742-ec8604682772").createMessage({
    message: {
        authorId: "7c15cbe7-21f1-4ff7-b742-ec8604682772",
        body: `#### Johannes Berge has requested a sample
The sample was delivered to:
> ROQ Tech
> Lorem Strasse 1
> 12345 Dusseldorf
Please Click [Documentation](https://docs.roq.tech/)`,
        conversationId: "cd05a61f-07ca-47e7-abc2-6f0ed9ab645d",
        isSystem: true,
    }
 
});
 
ParameterTypeDescription
message:authorIdstring!UserID of the message sender
message:bodystring!The body of the message, as a string or markdown
message:conversationIdstring!The ID of the conversation into which you want to send the message
message:ownerIdstring!The userId of the owner - i.e., usually the creator who has permission to archive the conversation
message:fileIdstring?If you want to include and attach a file with the message, specify a fileId
message:isSystemBoolean?System messages are styled differently in our UI components and can be used to visualize a message from a "bot" or a "system user"

Queries

messages()

Returns a list of chat messages for a given conversation. The API documentation for the messages() method is here (opens in a new tab).

roqClient.asSuperAdmin().messages({
    withFile: true,
    filter: {
      conversationId: { equalTo: 'your-conversationId' },
      fileId: {
        notEqualTo: null,
      },
    },
  })
  .then((response) => {
    console.log(response.messages);
  });

The messages() parameters support GraphQL Basics API such as order, limit, offset, and filter.

If you don't use the super admin user and the query isn't working, please check if the user has the related permission.

Image