Messages

Messages are the core of communication in Tether - they enable omnichannel messaging across SMS, Facebook Messenger, and Webchat. On this page, we will dive into the different message endpoints you can use to send and manage messages programmatically.

POST/api/messages/send

Send a message

This endpoint allows you to send a message to a contact through their preferred channel. The channel is determined by the contact's conversation settings.

Required attributes

  • Name
    contactId
    Type
    string
    Description

    The ID of the contact to send the message to.

  • Name
    content
    Type
    string
    Description

    The message content to send.

Optional attributes

  • Name
    conversationId
    Type
    string
    Description

    Specific conversation to send the message in.

  • Name
    attachments
    Type
    array
    Description

    Array of attachment URLs to include.

Request

POST
/api/messages/send
curl -X POST https://your-tether-instance.com/api/messages/send \
  -H "Authorization: Bearer {token}" \
  -H "Content-Type: application/json" \
  -d '{
    "contactId": "507f1f77bcf86cd799439011",
    "content": "Hello! How can I help you today?"
  }'

Response

{
  "_id": "507f1f77bcf86cd799439020",
  "conversationId": "507f1f77bcf86cd799439015",
  "contactId": "507f1f77bcf86cd799439011",
  "content": "Hello! How can I help you today?",
  "direction": "outbound",
  "channelType": "sms",
  "status": "sent",
  "sentBy": "507f1f77bcf86cd799439013",
  "isAIGenerated": false,
  "createdAt": "2025-01-15T10:30:00.000Z"
}
POST/api/messages/quick-bulk-send

Quick bulk send

This endpoint allows you to send the same message to multiple contacts at once. Useful for announcements or campaigns.

Required attributes

  • Name
    contactIds
    Type
    array
    Description

    Array of contact IDs to send the message to.

  • Name
    content
    Type
    string
    Description

    The message content to send to all contacts.

Request

POST
/api/messages/quick-bulk-send
curl -X POST https://your-tether-instance.com/api/messages/quick-bulk-send \
  -H "Authorization: Bearer {token}" \
  -H "Content-Type: application/json" \
  -d '{
    "contactIds": [
      "507f1f77bcf86cd799439011",
      "507f1f77bcf86cd799439012",
      "507f1f77bcf86cd799439013"
    ],
    "content": "Special offer: 20% off this weekend only!"
  }'

Response

{
  "success": true,
  "sent": 3,
  "failed": 0,
  "results": [
    { "contactId": "507f1f77bcf86cd799439011", "status": "sent" },
    { "contactId": "507f1f77bcf86cd799439012", "status": "sent" },
    { "contactId": "507f1f77bcf86cd799439013", "status": "sent" }
  ]
}
POST/api/messages/upload-attachment

Upload attachment

This endpoint allows you to upload an attachment (image, document, etc.) that can be included in messages.

Request

Send a multipart form data request with the file.

  • Name
    file
    Type
    file
    Description

    The file to upload.

Request

POST
/api/messages/upload-attachment
curl -X POST https://your-tether-instance.com/api/messages/upload-attachment \
  -H "Authorization: Bearer {token}" \
  -F "file=@/path/to/image.jpg"

Response

{
  "url": "https://s3.amazonaws.com/tether-attachments/507f1f77bcf86cd799439011/image.jpg",
  "filename": "image.jpg",
  "contentType": "image/jpeg",
  "size": 245678
}
GET/api/conversation/:id/messages

Get conversation messages

This endpoint retrieves all messages in a specific conversation, ordered by creation time.

Optional query parameters

  • Name
    limit
    Type
    integer
    Description

    Number of messages to return (default: 50).

  • Name
    before
    Type
    string
    Description

    Return messages before this message ID (for pagination).

Request

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

Response

{
  "messages": [
    {
      "_id": "507f1f77bcf86cd799439020",
      "conversationId": "507f1f77bcf86cd799439015",
      "content": "Hi, I am interested in your services",
      "direction": "inbound",
      "channelType": "sms",
      "status": "delivered",
      "createdAt": "2025-01-15T10:25:00.000Z"
    },
    {
      "_id": "507f1f77bcf86cd799439021",
      "conversationId": "507f1f77bcf86cd799439015",
      "content": "Hello! Thanks for reaching out. How can I help you?",
      "direction": "outbound",
      "channelType": "sms",
      "status": "delivered",
      "sentBy": "507f1f77bcf86cd799439013",
      "createdAt": "2025-01-15T10:30:00.000Z"
    }
  ],
  "hasMore": false
}

Message channels

Tether supports multiple messaging channels:

ChannelDescription
smsSMS text messages via Twilio or other providers
facebookFacebook Messenger integration
webchatWebsite chat widget

Messages are automatically routed to the appropriate channel based on the contact's conversation settings and the channel they originally contacted you through.

Real-time updates

For real-time message updates, Tether provides WebSocket connections via Socket.io. Connect to receive instant notifications when:

  • New messages are received
  • Message delivery status changes
  • Contacts read messages
Learn about webhooks for message events

Was this page helpful?