RATIO MACHINA STARTER logo

MERCURY

Conversations REST API

The Conversations REST API provides complete management of conversation threads between personas and contacts. Handle conversation lifecycle, threading, context management, and integration with external platforms.

Base URL & Authentication

Base URL: https://your-api-name.mercury.ratiomachina.com
Authentication: x-mercury-api-key: YOUR_API_KEY

List All Conversations

GET /conversations

Query Parameters

No query parameters supported. Returns all conversations.

Response Example

{
  "conversations": [
    {
      "id": "456e7890-e89b-12d3-a456-426614174000",
      "externalId": "conv789",
      "personaId": "789e4567-e89b-12d3-a456-426614174000",
      "contactId": "123e4567-e89b-12d3-a456-426614174000",
      "personaName": "Sales Agent",
      "contactName": "John Doe",
      "contactEmail": "john@example.com",
      "data": {"channel": "SMS", "priority": "high"},
      "createdAt": "2024-01-15T10:35:00Z",
      "updatedAt": "2024-01-15T10:45:00Z",
      "messageCount": 8,
      "latestMessage": {
        "sender": "persona",
        "message": "Thank you for your interest in our product!"
      }
    }
  ]
}

Create Conversation

POST /conversations

Request Body

{
  "contactExternalId": "customer123",
  "personaExternalId": "agent456",
  "conversationExternalId": "conv789",
  "conversationData": {
    "channel": "SMS",
    "priority": "high"
  },
  "contactData": {
    "source": "website"
  },
  "personaData": {
    "tone": "friendly"
  },
  "senderMessage": "Hello, I'm interested in your product",
  "senderExternalId": "customer123",
  "generatePersonaMessage": true,
  "addGeneratedMessageToConversation": true
}

Response Example

{
  "conversation": {
    "id": "456e7890-e89b-12d3-a456-426614174000",
    "externalId": "conv789",
    "personaId": "789e4567-e89b-12d3-a456-426614174000",
    "contactId": "123e4567-e89b-12d3-a456-426614174000",
    "persona": {
      "id": "789e4567-e89b-12d3-a456-426614174000",
      "externalId": "agent456",
      "name": "Sales Agent",
      "role": "sales",
      "data": {"tone": "friendly"}
    },
    "contact": {
      "id": "123e4567-e89b-12d3-a456-426614174000",
      "externalId": "customer123",
      "name": "John Doe",
      "email": "john@example.com",
      "data": {"source": "website"}
    },
    "data": {"channel": "SMS"},
    "messages": [
      {
        "id": "abc12345-e89b-12d3-a456-426614174000",
        "conversationId": "456e7890-e89b-12d3-a456-426614174000",
        "sender": "contact",
        "message": "Hello, I'm interested in your product",
        "data": {},
        "createdAt": "2024-01-15T10:35:00Z"
      }
    ],
    "lastMessage": {
      "id": "abc12345-e89b-12d3-a456-426614174000",
      "sender": "contact",
      "message": "Hello, I'm interested in your product",
      "createdAt": "2024-01-15T10:35:00Z"
    },
    "createdAt": "2024-01-15T10:35:00Z",
    "updatedAt": "2024-01-15T10:35:00Z"
  },
  "generatedPersonaMessage": {
    "message": "Thank you for your interest! How can I help you today?",
    "messageType": "initial",
    "status": "complete"
  }
}

Get Conversation by External ID

GET /conversations/{external_id}

Path Parameters

  • external_id - Conversation external ID

Query Parameters

No query parameters supported.

Response Example

{
  "conversation": {
    "id": "456e7890-e89b-12d3-a456-426614174000",
    "externalId": "conv789",
    "personaId": "789e4567-e89b-12d3-a456-426614174000",
    "contactId": "123e4567-e89b-12d3-a456-426614174000",
    "data": {"channel": "SMS"},
    "createdAt": "2024-01-15T10:35:00Z",
    "updatedAt": "2024-01-15T10:45:00Z",
    "messages": [
      {
        "id": "abc12345-e89b-12d3-a456-426614174000",
        "conversationId": "456e7890-e89b-12d3-a456-426614174000",
        "sender": "contact",
        "message": "Hello, I need help",
        "data": {},
        "createdAt": "2024-01-15T10:35:00Z"
      }
    ],
    "persona": {
      "id": "789e4567-e89b-12d3-a456-426614174000",
      "externalId": "agent456",
      "name": "Sales Agent",
      "data": {"tone": "friendly"},
      "createdAt": "2024-01-15T10:30:00Z",
      "updatedAt": "2024-01-15T10:30:00Z"
    },
    "contact": {
      "id": "123e4567-e89b-12d3-a456-426614174000",
      "externalId": "customer123",
      "name": "John Doe",
      "email": "john@example.com",
      "phone": "555-0123",
      "data": {"source": "website"},
      "createdAt": "2024-01-15T10:30:00Z",
      "updatedAt": "2024-01-15T10:30:00Z"
    }
  }
}

Update Conversation

PUT /conversations/{external_id}

Updates conversation data field. Supports partial updates - only provided fields will be modified.

Request Body

{
  "data": {
    "status": "active",
    "priority": "high",
    "channel": "SMS"
  }
}

Response Example

{
  "conversation": {
    "id": "456e7890-e89b-12d3-a456-426614174000",
    "externalId": "conv789",
    "contactId": "123e4567-e89b-12d3-a456-426614174000",
    "personaId": "789e4567-e89b-12d3-a456-426614174000",
    "data": {"status": "active", "priority": "high"},
    "createdAt": "2024-01-15T10:35:00Z",
    "updatedAt": "2024-01-15T11:45:00Z",
    "persona": {
      "name": "Sales Agent",
      "externalId": "agent456"
    },
    "contact": {
      "name": "John Doe",
      "externalId": "customer123"
    }
  }
}

Delete Conversation

DELETE /conversations/{external_id}

⚠️ Warning: Deleting a conversation will permanently remove all messages and cannot be undone. Consider archiving for data retention and compliance.

Path Parameters

  • external_id - Conversation external ID

Query Parameters

No query parameters supported.

Response Example

{
  "message": "Conversation deleted successfully",
  "deletedConversation": {
    "id": "456e7890-e89b-12d3-a456-426614174000",
    "externalId": "conv789",
    "external_id": "conv789",
    "contactId": "123e4567-e89b-12d3-a456-426614174000",
    "contact_id": "123e4567-e89b-12d3-a456-426614174000",
    "personaId": "789e4567-e89b-12d3-a456-426614174000",
    "persona_id": "789e4567-e89b-12d3-a456-426614174000"
  }
}

Batch Archive Conversations

POST /batch-ops/conversations/archive

Archive multiple conversations by their external IDs instead of deleting them. Archived conversations retain all data.

Request Body

{
  "external_ids": [
    "sales-lead-john-001",
    "support-ticket-mary-456"
  ]
}

Response Example

{
  "message": "2 conversation(s) archived successfully",
  "archived": [
    {
      "id": "123e4567-e89b-12d3-a456-426614174000",
      "externalId": "sales-lead-john-001",
      "name": "Sales Lead John",
      "archived": true
    },
    {
      "id": "123e4567-e89b-12d3-a456-426614174001",
      "externalId": "support-ticket-mary-456",
      "name": "Support Ticket Mary",
      "archived": true
    }
  ],
  "archived_count": 2,
  "already_archived_count": 0,
  "not_found_count": 0
}

Batch Delete Conversations

DELETE /batch-ops/conversations

Delete multiple conversations by their external IDs.

⚠️ Warning: This will permanently delete the conversations and all associated messages.

Request Body

{
  "external_ids": [
    "sales-lead-john-001",
    "support-ticket-mary-456"
  ]
}

Response Example

{
  "message": "2 conversation(s) deleted successfully",
  "deletedCount": 2,
  "deletedConversations": [
    {
      "id": "123e4567-e89b-12d3-a456-426614174000",
      "externalId": "sales-lead-john-001",
      "name": "Sales Lead John"
    },
    {
      "id": "123e4567-e89b-12d3-a456-426614174001",
      "externalId": "support-ticket-mary-456",
      "name": "Support Ticket Mary"
    }
  ],
  "notFound": []
}

Conversations API Best Practices

Thread Management

  • Use external IDs for platform integration
  • Archive completed conversations for compliance
  • Implement proper escalation workflows
  • Maintain conversation context and metadata

Performance & Monitoring

  • Monitor response times and satisfaction scores
  • Use conversation summaries for reporting
  • Export data regularly for backup
  • Track sentiment and engagement metrics
← Contacts APIMessages API →
Transcend the hype with MERCURY by Ratio Machina