Conversations

Conversations represent multi-channel communication threads between your organization and contacts. Each conversation belongs to a contact and tracks messages across SMS, Facebook Messenger, or Webchat. On this page, we'll dive into the different conversation endpoints you can use to manage conversations programmatically.

POST/api/conversation/all

Get conversations by contact

This endpoint allows you to retrieve all conversations for a specific contact. Returns conversations the authenticated user has access to based on ownership or assignment.

Required attributes

Name
contactId
Type
string
Description
The ID of the contact to retrieve conversations for.

Optional attributes

Name
channelType
Type
string
Description
Filter by channel type (default: "sms").

Request

POST

/api/conversation/all

curl https://your-tether-instance.com/api/conversation/all \
  -H "Authorization: Bearer {token}" \
  -H "Content-Type: application/json" \
  -d '{
    "contactId": "507f1f77bcf86cd799439011",
    "channelType": "sms"
  }'

Response

{
  "conversations": [
    {
      "_id": "507f1f77bcf86cd799439030",
      "organizationId": "507f1f77bcf86cd799439012",
      "userId": "507f1f77bcf86cd799439013",
      "assignees": [
        {
          "_id": "507f1f77bcf86cd799439013",
          "fullName": "Sales Rep",
          "email": "rep@example.com"
        }
      ],
      "channelType": "sms",
      "channelIdentifier": "+1234567890",
      "latestMessage": "6934da797e62b453609a438b",
      "lastMessageTime": "2025-01-15T12:30:00.000Z",
      "isResolved": false,
      "resolvedAt": null,
      "subject": null,
      "provider": null,
      "emailAccountId": null,
      "participants": null,
      "isDraft": false,
      "messageCount": 15,
      "createdAt": "2025-01-15T10:00:00.000Z",
      "updatedAt": "2025-01-15T12:30:00.000Z"
    }
  ]
}

POST/api/conversation/messages

Get messages by conversation

This endpoint allows you to retrieve all messages within a specific conversation.

Required attributes

Name
conversationId
Type
string
Description
The ID of the conversation to retrieve messages for.

Request

POST

/api/conversation/messages

curl https://your-tether-instance.com/api/conversation/messages \
  -H "Authorization: Bearer {token}" \
  -H "Content-Type: application/json" \
  -d '{"conversationId": "507f1f77bcf86cd799439030"}'

Response

{
  "messages": [
    {
      "_id": "6934c2d26c75ebcd6439f143",
      "isIncoming": false,
      "body": "Hey",
      "channelType": "sms",
      "channelIdentifier": "+15879897422",
      "status": "delivered",
      "senderType": "AI",
      "userId": {
        "_id": "68cd6b13f5b13e3d2da22e8f",
        "fullName": "Tether Dev"
      },
      "contactId": "69348e7b7e62b453609a197a",
      "attachments": [],
      "systemStamp": {
        "fieldsExtracted": [],
        "actions": []
      },
      "createdAt": "2025-12-06T23:57:06.692Z"
    },
    {
      "_id": "6934da797e62b453609a438b",
      "isIncoming": false,
      "body": "",
      "channelType": "sms",
      "channelIdentifier": "+15879897422",
      "status": "delivered",
      "senderType": "SYSTEM",
      "userId": {
        "_id": "68cd6b13f5b13e3d2da22e8f",
        "fullName": "Tether Dev"
      },
      "contactId": "69348e7b7e62b453609a197a",
      "attachments": [],
      "systemStamp": {
        "type": "automation",
        "automationName": "Lead follow-up",
        "fieldsExtracted": ["firstName"],
        "actions": ["create_lead"]
      },
      "createdAt": "2025-12-07T01:38:01.438Z"
    }
  ]
}

GET/api/conversation/:id

Retrieve a conversation

This endpoint allows you to retrieve a conversation by providing its ID.

Request

GET

/api/conversation/:id

curl https://your-tether-instance.com/api/conversation/507f1f77bcf86cd799439030 \
  -H "Authorization: Bearer {token}"

Response

{
    "data": {
        "_id": "6934c2d26c75ebcd6439f140",
        "contactId": "69348e7b7e62b453609a197a",
        "organizationId": "68d504c9aa4c0ca510f46fed",
        "process": "68ce650fbb408b94941a43d2",
        "isAutopilot": true,
        "source": "Outbound Message",
        "leadSource": "any",
        "userId": "68cd6b13f5b13e3d2da22e8f",
        "assignees": [],
        "channelType": "sms",
        "channelIdentifier": "+15879897422",
        "isUpdated": false,
        "isResolved": true,
        "lastMessageTime": "2025-12-07T01:38:01.509Z",
        "createdAt": "2025-12-06T23:57:06.536Z",
        "updatedAt": "2025-12-10T12:03:06.524Z",
        "__v": 0,
        "latestMessage": "6934da797e62b453609a438b",
        "resolvedAt": "2025-12-10T12:03:06.508Z"
    }
}

PUT/api/conversation/:id

Update a conversation

This endpoint allows you to update a conversation. You can update assignees, resolution status, or other conversation metadata.

Optional attributes

Name
assignees
Type
array
Description
Array of user IDs to assign to the conversation.
Name
isResolved
Type
boolean
Description
Mark the conversation as resolved or unresolved.

Request

PUT

/api/conversation/:id

curl -X PUT https://your-tether-instance.com/api/conversation/507f1f77bcf86cd799439030 \
  -H "Authorization: Bearer {token}" \
  -H "Content-Type: application/json" \
  -d '{
    "assignees": ["507f1f77bcf86cd799439013"],
    "isResolved": false
  }'

Response

{
  "data": {
    "_id": "6934c2d26c75ebcd6439f140",
    "contactId": "69348e7b7e62b453609a197a",
    "organizationId": "68d504c9aa4c0ca510f46fed",
    "process": "68ce650fbb408b94941a43d2",
    "isAutopilot": true,
    "source": "Outbound Message",
    "leadSource": "any",
    "userId": "68cd6b13f5b13e3d2da22e8f",
    "assignees": [
      {
        "_id": "507f1f77bcf86cd799439013",
        "fullName": "Sales Rep",
        "email": "rep@example.com"
      }
    ],
    "channelType": "sms",
    "channelIdentifier": "+15879897422",
    "isUpdated": false,
    "isResolved": false,
    "lastMessageTime": "2025-12-07T01:38:01.509Z",
    "createdAt": "2025-12-06T23:57:06.536Z",
    "updatedAt": "2025-01-15T13:00:00.000Z",
    "__v": 0,
    "latestMessage": "6934da797e62b453609a438b"
  }
}

PUT/api/conversation/:id/resolve

Toggle resolve conversation

This endpoint allows you to set the resolution status of a conversation.

Required attributes

Name
isResolved
Type
boolean
Description
Set to true to resolve the conversation, false to unresolve it.

Request

PUT

/api/conversation/:id/resolve

curl -X PUT https://your-tether-instance.com/api/conversation/507f1f77bcf86cd799439030/resolve \
  -H "Authorization: Bearer {token}" \
  -H "Content-Type: application/json" \
  -d '{"isResolved": true}'

Response

{
  "message": "Conversation resolved successfully",
  "data": {
    "_id": "507f1f77bcf86cd799439030",
    "isResolved": true,
    "resolvedAt": "2025-01-15T13:30:00.000Z"
  }
}

POST/api/conversation/unseen

Mark conversation as unseen

This endpoint allows you to mark a conversation as unseen, useful for marking conversations that need attention.

Required attributes

Name
conversationId
Type
string
Description
The ID of the conversation to mark as unseen.

Request

POST

/api/conversation/unseen

curl https://your-tether-instance.com/api/conversation/unseen \
  -H "Authorization: Bearer {token}" \
  -H "Content-Type: application/json" \
  -d '{"conversationId": "507f1f77bcf86cd799439030"}'

Response

{
  "message": "Conversation updated successfully."
}

DELETE/api/conversation

Delete a conversation

This endpoint allows you to delete a conversation. Note: This will also delete all messages associated with the conversation.

Required attributes

Name
conversationId
Type
string
Description
The ID of the conversation to delete (in request body).

Request

DELETE

/api/conversation

curl -X DELETE https://your-tether-instance.com/api/conversation \
  -H "Authorization: Bearer {token}" \
  -H "Content-Type: application/json" \
  -d '{"conversationId": "507f1f77bcf86cd799439030"}'

Response

{
  "message": "Conversation cleared successfully"
}