Messages

Advertencia

Esta página aún no se encuentra traducida al español.

Overview

Messages are sent through the channel workspace chat. Messages can contain text, multimedia files, answered surveys, or system-generated responses.

Through this endpoint, you can access message content sent in your company's channels.

additional resources

These are just some of the most basic API requests. For a complete list of endpoints, consult our API documentation on Swagger.

Get Messages Sent After Modified Date

Get all the messages in a channel modified after the indicated date and time..

GET /messages/channel/{id}/modified/{modified}

Endpoint URL

https://www.cotalker.com/api/v1/messages/channel/{id}/modified/{modified}

Path Parameters

Parameter	Description	Type	Required	Values
id	The ObjectId of the channel to retrieve the messages from.	ObjectId<COTChannel>	Required
modified	Indicates the date and time from which sent messages are retrieved.	ISODate	Required	YYYY-MM-DDTHH:mm:ss.SSSZ

Headers

Header	Description	Required	Values
Authorization	Sends your access token to make an API request. Click here to see how to obtain an access token.	Required	Bearer $ACCESS_TOKEN

Request Samples

This request returns all messages sent on and after September 6, 2021 in the specified channel.

curl --location --request GET 'https://www.cotalker.com/api/v1/messages/channel/60d382fbd5f06600095531c8/modified/2021-09-06T00:00:00.000Z' \
--header 'Authorization: Bearer $ACCESS_TOKEN'

Response Sample

Responses follow the COTMessage data model.

Send a Message

Sends a message to a channel.

POST /messages

Endpoint URL

https://www.cotalker.com/api/v1/messages

Headers

Header	Description	Required	Values
Authorization	Sends your access token to make an API request. Click here to see how to obtain an access token.	Required	Bearer $ACCESS_TOKEN
Content-Type	Indicates the body's format.	Required	application/json

Request Body

Only required fields are listed below. For a complete schema description, please go to the COTChannel data model. Unrequired fields that are not submitted are either filled in automatically or left blank.

Element	Description	Type	Required	Notes
channel	The channel the message is sent in.	ObjectId<COTChannel>	Required
content	Displayed data; could be user text input, system message, or file object.	string	Required (for all messages that are not surveys)	For details about the type of content allowed, go to COTMessageContentType.
contentArray	Array of answered survey questions	ObjectId<COTQuestion>[ ]	Required (if sending a survey)
contentType	Indicates content type, for example: `text/plain` (user text input), `application/vnd.cotalker.survey` (answered survey), `application/pdf` (pdf file), `image/gif` (uploaded gif image)	string	Required	For a complete list of content types, go to COTMessageContentType. See below for enriched messages.
isSaved	Used to indicate the message state. `2` is used for sending a regular message; `8` is used for sending unanswered surveys; `16` is used to indicate a message has already been delivered.	number	Required	Use with precaution; consult the Cotalker Platform Community for further details.
sentBy	ID of the user that sends the message.	ObjectId<COTUser>	Required

Request Sample

Message sent with the minimum required fields:

curl --location --request POST 'https://www.cotalker.com/api/v1/messages' \
--header 'Authorization: Bearer $ACCESS_TOKEN' \
--header 'Content-Type: application/json' \
--data-raw '{
    "channel": "619b8cf2107bbec0876cddf2",
    "content": "Hello, world!",
    "contentType": "text/plain",
    "isSaved": 2,
    "sentBy": "61953bf9bdc3558a4966e54d"
}'

Response Sample

Go to COTMessage for a complete description of the response.

{
    "form": {
        "modifiedAt": []
    },
    "content": "Hello, world!",
    "contentArray": [],
    "reply": [],
    "_id": "619cd2c9df0b22b7e8f9d556",
    "channel": "619b8cf2107bbec0876cddf2",
    "contentType": "text/plain",
    "isSaved": 16,
    "sentBy": "61953bf9bdc3558a4966e54d",
    "createdAt": 1637664207913,
    "modifiedAt": "2021-11-23T10:43:27.922Z"
}

Edit a Message

Edits the indicated message.

PATCH /messages/{id}

Endpoint URL

https://www.cotalker.com/api/v1/messages/{id}

Path Parameters

Parameter	Description	Type	Required	Notes
id	The ObjectId of the message to be modified.	ObjectId<COTMessage>	Required

Headers

Header	Description	Required	Values
Authorization	Sends your access token to make an API request. Click here to see how to obtain an access token.	Required	Bearer $ACCESS_TOKEN
Content-Type	Sets the body's format.	Required	application/json

Request Body

Fields that are being edited or added are required to be put into the body. Additionally, the following fields must also be in the body. For a complete schema description, please go to the COTMessage data model.

Element	Description	Type	Required	Notes
channel	The channel the message is sent in.	ObjectId<COTChannel>	Required
isSaved	Used to indicate the message state. `2` is used for sending a regular message; `8` is used for sending unanswered surveys; `16` is used to indicate a message has already been delivered.	number	Required	Use with precaution; consult the Cotalker Platform Community for further details.

Request Sample

Edit a sent message:

curl --location --request PATCH 'https://www.cotalker.com/api/v1/messages/619cd2c9df0b22b7e8f9d556' \
--header 'Authorization: Bearer $ACCESS_TOKEN' \
--header 'Content-Type: application/json' \
--data-raw '{
    "content": "I am editing this message with an API request!",
    "isSaved": 2,
    "channel": "619b8cf2107bbec0876cddf2"
}'

Response Sample

Go to COTMessage for a complete description of the response.

{
    "form": {
        "modifiedAt": []
    },
    "content": "I am editing this message with an API request!",
    "contentArray": [],
    "reply": [],
    "_id": "619cd2c9df0b22b7e8f9d556",
    "channel": "619b8cf2107bbec0876cddf2",
    "contentType": "text/plain",
    "isSaved": 16,
    "sentBy": "61953bf9bdc3558a4966e54d",
    "createdAt": 1637664207913,
    "modifiedAt": "2021-11-23T10:43:27.922Z"
}

Remove a Message

Removes the indicated message from the channel. Can be reverted.

PATCH /messages/{id}/remove

Endpoint URL

https://www.cotalker.com/api/v1/messages/{id}/remove

Path Parameters

Parameter	Description	Type	Required	Notes
id	The ObjectId of the message to be removed.	ObjectId<COTMessage>	Required

Headers

Header	Description	Required	Values
Authorization	Sends your access token to make an API request. Click here to see how to obtain an access token.	Required	Bearer $ACCESS_TOKEN

Request Sample

Remove a message from a channel:

curl --location --request PATCH 'https://www.cotalker.com/api/v1/messages/619cd2c9df0b22b7e8f9d556/remove' \
--header 'Authorization: Bearer $ACCESS_TOKEN'

Response Sample

Go to COTMessage for a complete description of the response.

{
    "form": {
        "modifiedAt": []
    },
    "content": "I am editing this message with an API request!",
    "contentArray": [],
    "reply": [],
    "_id": "619cd2c9df0b22b7e8f9d556",
    "channel": "619b8cf2107bbec0876cddf2",
    "contentType": "text/plain",
    "isSaved": 16,
    "sentBy": "61953bf9bdc3558a4966e54d",
    "createdAt": 1637664207913,
    "modifiedAt": "2021-11-23T13:06:14.066Z",
    "isHidden": true
}

note

To revert the removal of a message from the channel, edit the message and change the value of the isHidden field to false.

Send an Enriched Message

Special syntax for sending enriched messages.

POST /messages

Endpoint URL

https://www.cotalker.com/api/v1/messages

Headers

Header	Description	Required	Values
Authorization	Sends your access token to make an API request. Click here to see how to obtain an access token.	Required	Bearer $ACCESS_TOKEN
Content-Type	Indicates the body's format.	Required	application/json

Request Body

Element	Description	Type	Required	Notes
channel	The channel the message is sent in.	ObjectId<COTChannel>	Required
contentType	Use the `text/enriched` option to send enriched messeages.	string	Required	Notes
contentParts	Indicates the format and content to use in each part of the sent message.	Object[ ]	Required	See samples.
contentParts[x].type	Content part types include: `text`, `link`, `hover`, and `task`.	string	Required
contentParts[x].content	The text displayed in the message. In case of `link`, `hover`, and `task` types, the text is linked to the respective `payload` data.	string	Required
contentParts[x].payload	The data linked to the text in `contentParts.content`. Each `contentParts.type` has a specific `payload` object.	object	Required
contentParts[x].payload.url	Indicates the linked URL when using the `link` type.	string	Required when using the `link` type.
contentParts[x].payload.card	The data displayed when hovering over `hover` type content.	object	Required when using the `hover` type.
contentParts[x].payload.card.image	URL of the image that is displayed on the pop-up card.	string	Required when using the `hover` type.
contentParts[x].payload.card.text	The text that is displayed on the pop-up card.	string	Required when using the `hover` type.
contentParts[x].payload.company	ObjectId of the company in which the message is sent.	ObjectId<COTCompany>	Required when using the `task` type.
contentParts[x].payload.task	ObjectId of the task that is linked to the `contentParts.content` text.	ObjectId<COTTask>	Required when using the `task` type.
contentParts[x].payload.taskGroup	ObjectId of the task group in which the task is found.	ObjectId<COTTaskGroup>	Required when using the `task` type.
isSaved	This field must be set to `2` to send the message.	number	Required
sentBy	ID of the user that sends the message.	ObjectId<COTUser>	Required

Request Sample

Message sent with the minimum required fields:

curl --location --request POST 'https://dev.cotalker.com/api/v1/messages' \
--header 'Admin: true' \
--header 'Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJfaWQiOiI2MjJhYjE2MzVhODcwMjAwMDdjMjA1MzMiLCJyb2xlIjoidXNlciIsImNvbXBhbnkiOiI2MjJhYjE0ZjcxYjEyZDdkNDExMjhkOGUiLCJkYXRlIjoxNjQ3NTIyNjc5ODk2LCJpcnQiOnRydWUsImlhdCI6MTY0NzUyMjY3OSwiZXhwIjoxNjUwMTE0Njc5fQ.qsQbBk8-4lqEcvmTv-D34x0N6gXjwAp_EWC2QbBFITQ' \
--header 'Content-Type: application/json' \
--data-raw '{
    "channel": "623b136680753a589460c368",
    "contentType": "text/enriched",
    "isSaved": 2,
    "sentBy": "623b137046abafdd25f1e88c",
    "contentParts": [
        {
            "type": "text",
            "content": "This is an automatically-generated message regarding the"
        },
        {
            "type": "task",
            "content": "Fix Pipes Work Order.",
            "payload": {
                "company": "623b1332d6bf5d4380821b7d",
                "task": "623b137c3f85e5110df8cd59",
                "taskGroup": "623b138279d4089a60cf2984"
            }
        },
        {
            "type": "user",
            "content": "@Thomas Gardner",
            "payload": {
                "user": "623b138df83745aa22ba6462",
                "company": "623b1332d6bf5d4380821b7d"
            }
        },
        {
            "type": "text",
            "content": "has requested to"
        },
        {
            "type": "hover",
            "content": "close the work order.",
            "payload": {
                "card": {
                    "image": "https://doc.cotalker.com/img/products/products_work_orders_workflow_forms_10.png",
                    "text": "When contractors request to close a work order, supervisors receive a copy of the Close Work Order form. They must then inspect the completed job and fill out the Acceptance of Work form, where they indicate whether the job can be accepted. If accepted, the job is officially completed and the work order is closed."
                }
            }
        },
        {
            "type": "text",
            "content": "Please fill out the Acceptance of Work form."
        },
        {
            "type": "link",
            "content": "Click here for more information.",
            "payload": {
                "url": "https://doc.cotalker.com/docs/products/workflows/work_orders/surveys-acceptance"
            }
        }
    ]
}'

Response Sample

Go to COTMessage for a complete description of the response.

{
    "form": {
        "modifiedAt": []
    },
    "cmd": {
        "ids": []
    },
    "content": "This is an automatically-generated message regarding the Fix Pipes Work Order. @Thomas Gardner has requested to close the work order. Please fill out the Acceptance of Work form. Click here for more information.",
    "contentArray": [],
    "isActive": true,
    "reply": [],
    "_id": "623b16340a0e75cc2a6d5819",
    "channel": "623b136680753a589460c368",
    "contentType": "text/enriched",
    "isSaved": 16,
    "sentBy": "623b137046abafdd25f1e88c",
    "contentParts": [
        {
            "type": "text",
            "_id": "623b16af2baa9c957d5ce07c",
            "content": "This is an automatically-generated message regarding the"
        },
        {
            "type": "task",
            "_id": "623b16ba766ca92429381bb6",
            "content": "Fix Pipes Work Order.",
            "payload": {
                "company": "623b1332d6bf5d4380821b7d",
                "task": "623b137c3f85e5110df8cd59",
                "taskGroup": "623b138279d4089a60cf2984"
            }
        },
        {
            "type": "user",
            "_id": "623b16c0e8bbb2e9750816c4",
            "content": "@Thomas Gardner",
            "payload": {
                "user": "623b138df83745aa22ba6462",
                "company": "623b1332d6bf5d4380821b7d"
            }
        },
        {
            "type": "text",
            "_id": "623b16c838100f2362b52363",
            "content": "has requested to"
        },
        {
            "type": "hover",
            "_id": "623b16d18a9b122102c770f6",
            "content": "close the work order.",
            "payload": {
                "card": {
                    "image": "https://doc.cotalker.com/img/products/products_work_orders_workflow_forms_10.png",
                    "text": "When contractors request to close a work order, supervisors receive a copy of the Close Work Order form. They must then inspect the completed job and fill out the Acceptance of Work form, where they indicate whether the job can be accepted. If accepted, the job is officially completed and the work order is closed."
                }
            }
        },
        {
            "type": "text",
            "_id": "623b16d80cd4f139d3c70aee",
            "content": "Please fill out the Acceptance of Work form."
        },
        {
            "type": "link",
            "_id": "623b16df08635dfb42c8c57b",
            "content": "Click here for more information.",
            "payload": {
                "url": "https://dev.cotalker.com/api/redirect/r/623a065fc6bed20007066384",
                "ogMetadata": {
                    "title": "Work Orders Workflow | Cotalker Technical Documentation",
                    "image": "https://doc.cotalker.com/img/products/products_work_orders_workflow_forms_11.png",
                    "url": "https://doc.cotalker.com/docs/products/workflows/work_orders/surveys-acceptance",
                    "description": "Survey Forms",
                    "video": null,
                    "audio": null,
                    "logo": null,
                    "publisher": null,
                    "author": null,
                    "date": null
                }
            }
        }
    ],
    "createdAt": 1648038890202,
    "responses": [],
    "readBy": [],
    "modifiedAt": "2022-03-23T12:34:50.714Z"
}

tip

See how enriched messages are displayed on channel workspaces.

Overview​

Get Messages Sent After Modified Date​

Endpoint URL​

Path Parameters​

Headers​

Request Samples​

Response Sample​

Send a Message​

Endpoint URL​

Headers​

Request Body​

Request Sample​

Response Sample​

Edit a Message​

Endpoint URL​

Path Parameters​

Headers​

Request Body​

Request Sample​

Response Sample​

Remove a Message​

Endpoint URL​

Path Parameters​

Headers​

Request Sample​

Response Sample​

Send an Enriched Message​

Endpoint URL​

Headers​

Request Body​

Request Sample​

Response Sample​

Overview

Get Messages Sent After Modified Date

Endpoint URL

Path Parameters

Headers

Request Samples

Response Sample

Send a Message

Endpoint URL

Headers

Request Body

Request Sample

Response Sample

Edit a Message

Endpoint URL

Path Parameters

Headers

Request Body

Request Sample

Response Sample

Remove a Message

Endpoint URL

Path Parameters

Headers

Request Sample

Response Sample

Send an Enriched Message

Endpoint URL

Headers

Request Body

Request Sample

Response Sample