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"],
    },
});

Parameter	Type	Description
`conversation: archived`	Boolean?	Is the conversation archived or not
`conversation:isGroup`	Boolean?	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:memberIds`	string[]!	An array of userIds for participants of the conversation
`conversation:ownerId`	string!	The userId of the owner - i.e. usually the creator who has permission to archive the conversation
`conversation:tags`	string[]?	An array of strings. These may be used to filter conversations on the UI Components
`conversation:title`	string!	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"
});

Parameter	Type	Description
`id`	uuid	Conversation 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"]
});

Parameter	Type	Description
`conversationId`	uuid	The conversation ID
`tags`	array	Array 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"]
});

Parameter	Type	Description
`conversationId`	uuid	The conversation ID
`tags`	array	Array 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,
    }
 
});

Parameter	Type	Description
`message:authorId`	string!	UserID of the message sender
`message:body`	string!	The body of the message, as a string or markdown
`message:conversationId`	string!	The ID of the conversation into which you want to send the message
`message:ownerId`	string!	The userId of the owner - i.e., usually the creator who has permission to archive the conversation
`message:fileId`	string?	If you want to include and attach a file with the message, specify a fileId
`message:isSystem`	Boolean?	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

`conversations()`

To get all the conversations, we can use the conversations() method API. The documentation for this API is here (opens in a new tab).

const chats = await roqClient.asSuperAdmin().conversations({
	limit: 10,
	withUsers: true,
	withTags: true
})

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

`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.

Overview UI Components