Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.messagesender.ai/llms.txt

Use this file to discover all available pages before exploring further.

Conversations in Amplifi represent the two-way SMS threads between your organization and individual contacts. Each conversation is keyed by a contact’s phone number and contains both inbound messages received from the contact and outbound messages sent by your team or campaigns. The conversations API lets you list active threads, fetch message history, and send replies programmatically.

​
List conversations


GET /api/conversations
Returns conversation threads for your organization. Each thread represents all message activity with one phone number. By default, all conversations are returned; use query parameters to filter.

​
Query parameters

​
unread
boolean
When true, returns only conversations that have unread inbound messages.
​
unresponded
boolean
When true, returns only conversations where the last message was inbound (contact replied but your team has not yet responded).
​
search
string
Search conversations by contact name or phone number.
​
includeArchived
boolean
When true, includes archived conversations. Defaults to false.

​
Response

[
  {
    "phoneNumber": "+19195551234",
    "contactId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "firstName": "Jane",
    "lastName": "Smith",
    "lastMessage": "Sounds great, see you there!",
    "lastMessageAt": "2025-04-23T18:45:00.000Z",
    "unreadCount": 1,
    "isArchived": false,
    "isStarred": false
  }
]

​
Get conversation messages


GET /api/conversations/:phoneNumber/messages
Returns the message history for a single conversation, identified by the contact’s phone number. Messages are returned in reverse chronological order (newest first) using keyset pagination. Timestamps are always returned in UTC ISO 8601 format.

​
Path parameters

​
phoneNumber
string
required
The contact’s phone number. Accepts any standard US format; it is normalized to E.164 internally.

​
Query parameters

​
limit
number
Number of messages to return per page. Default 50, max 200.
​
cursor
string
Keyset pagination cursor from a previous response. Pass the cursor value to fetch older messages.

​
Response

{
  "messages": [
    {
      "id": "f6a7b8c9-d0e1-2345-fghi-678901234567",
      "direction": "incoming",
      "message": "Sounds great, see you there!",
      "mediaUrl": null,
      "mediaUrls": null,
      "status": null,
      "sentiment": "positive",
      "sentimentScore": 0.92,
      "messageCategory": "general",
      "requiresResponse": false,
      "optOutDetected": false,
      "timestamp": "2025-04-23T18:45:00.000Z"
    },
    {
      "id": "e5f6a7b8-c9d0-1234-efgh-567890123456",
      "direction": "outgoing",
      "message": "Hi Jane, just confirming your RSVP for April 28!",
      "mediaUrl": null,
      "status": "delivered",
      "timestamp": "2025-04-23T17:30:00.000Z"
    }
  ],
  "timezone": "America/New_York"
}

​
Response fields

​
messages[].direction
string
incoming for messages received from the contact, outgoing for messages sent by your organization.
​
messages[].status
string | null
Delivery status for outgoing messages: sent, delivered, failed, or undelivered. null for incoming messages.
​
messages[].sentiment
string | null
Detected sentiment of inbound messages: positive, negative, or neutral. null if not yet analyzed.
​
messages[].optOutDetected
boolean | null
true if this inbound message was detected as an opt-out request (e.g. STOP, UNSUBSCRIBE).
​
messages[].requiresResponse
boolean | null
true if the platform has flagged this inbound message as needing a reply.
​
timezone
string
The organization’s configured timezone, useful for displaying timestamps in local time.

​
Send a reply


POST /api/conversations/:phoneNumber/reply
Sends a reply message to the contact identified by phoneNumber. The contact must exist in your organization and must be textable (isTextable: true) and opted in (isOptedIn: true). Replies sent through this endpoint bypass quiet hours and are delivered immediately, regardless of the time of day. Use this for time-sensitive individual responses, not bulk outreach.

​
Path parameters

​
phoneNumber
string
required
The recipient’s phone number. Accepts any standard US format.

​
Request body

​
message
string
required
The message text to send. Must be a non-empty string.
​
fromPhoneNumberId
string (UUID)
UUID of the sending phone number. Defaults to your organization’s default phone number.
​
mediaUrl
string
Public URL of media to attach. When provided, the message is sent as MMS.
​
normalizeText
boolean
When true (default), normalizes smart quotes and non-ASCII characters before sending.
​
forceRoute
string
Override routing: AUTO (default), SMS, or MMS.

​
Example request

curl -X POST "https://api.amplifi.com/api/conversations/%2B19195551234/reply" \
  -H "Authorization: Bearer <token>" \
  -H "x-organization-id: 3f4e5c6d-7a8b-9012-cdef-1234567890ab" \
  -H "Content-Type: application/json" \
  -d '{
    "message": "Thanks for reaching out! Our team will follow up shortly.",
    "fromPhoneNumberId": "a2b3c4d5-e6f7-8901-bcde-f23456789012"
  }'

​
Response

{
  "success": true,
  "messageLog": {
    "id": "g7h8i9j0-k1l2-3456-mnop-789012345678",
    "phoneNumber": "+19195551234",
    "message": "Thanks for reaching out! Our team will follow up shortly.",
    "status": "sent",
    "sentAt": "2025-04-24T10:30:00.000Z"
  },
  "provider": "twilio",
  "providerMessageId": "SM1234567890abcdef1234567890abcdef"
}

​
Error responses

StatusCodeMeaning
400CONTACT_NOT_FOUNDNo contact exists with this phone number. Create the contact first.
400CONTACT_OPTED_OUTThe contact has opted out and cannot receive messages.
400CONTACT_NON_TEXTABLEThe contact’s number is confirmed non-textable (landline, VOIP, etc.).
400NO_FROM_NUMBERYour organization has no default phone number configured.
402—Insufficient credits to send the message.
403—The specified fromPhoneNumberId does not belong to your organization.
If a contact’s isTextable value is null (lookup pending), replies are blocked until the lookup completes. A contact that has previously sent you an inbound message is automatically marked textable.
URLs included in reply messages are automatically shortened using your organization’s configured link-shortening service, enabling click tracking.