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",
      "contactId": "507f1f77bcf86cd799439011",
      "organizationId": "507f1f77bcf86cd799439012",
      "userId": "507f1f77bcf86cd799439013",
      "assignees": [
        {
          "_id": "507f1f77bcf86cd799439013",
          "fullName": "Sales Rep",
          "email": "rep@example.com"
        }
      ],
      "channelType": "sms",
      "channelIdentifier": "+1234567890",
      "latestMessage": "Thanks for your help!",
      "lastMessageTime": "2025-01-15T12:30:00.000Z",
      "isResolved": 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": "507f1f77bcf86cd799439040",
      "conversationId": "507f1f77bcf86cd799439030",
      "contactId": "507f1f77bcf86cd799439011",
      "organizationId": "507f1f77bcf86cd799439012",
      "content": "Hello, I'm interested in financing",
      "direction": "inbound",
      "channelType": "sms",
      "status": "delivered",
      "createdAt": "2025-01-15T10:05:00.000Z"
    },
    {
      "_id": "507f1f77bcf86cd799439041",
      "conversationId": "507f1f77bcf86cd799439030",
      "contactId": "507f1f77bcf86cd799439011",
      "organizationId": "507f1f77bcf86cd799439012",
      "content": "Great! I can help you with that.",
      "direction": "outbound",
      "channelType": "sms",
      "status": "delivered",
      "createdAt": "2025-01-15T10:06:00.000Z"
    }
  ]
}

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

{
  "_id": "507f1f77bcf86cd799439030",
  "contactId": "507f1f77bcf86cd799439011",
  "organizationId": "507f1f77bcf86cd799439012",
  "userId": "507f1f77bcf86cd799439013",
  "assignees": ["507f1f77bcf86cd799439013"],
  "channelType": "sms",
  "channelIdentifier": "+1234567890",
  "latestMessage": "Thanks for your help!",
  "lastMessageTime": "2025-01-15T12:30:00.000Z",
  "isResolved": false,
  "createdAt": "2025-01-15T10:00:00.000Z",
  "updatedAt": "2025-01-15T12:30:00.000Z"
}

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

{
  "message": "Conversation updated successfully",
  "conversation": {
    "_id": "507f1f77bcf86cd799439030",
    "assignees": ["507f1f77bcf86cd799439013"],
    "isResolved": false,
    "updatedAt": "2025-01-15T13:00:00.000Z"
  }
}

PUT/api/conversation/:id/resolve

Toggle resolve conversation

This endpoint allows you to toggle the resolution status of a conversation. If the conversation is resolved, it will be marked as unresolved, and vice versa.

Request

PUT

/api/conversation/:id/resolve

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

Response

{
  "message": "Conversation resolved successfully",
  "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 marked as unseen"
}

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 deleted successfully"
}