The Conversation Design RPC API provides advanced operations that go beyond simple CRUD, including resource upserts, AI-powered message generation, and skill execution. These endpoints are optimized for complex workflows and external system integrations.
Base URL: https://your-api-name.mercury.ratiomachina.com Authentication: x-mercury-api-key: YOUR_API_KEY
š Primary Integration Endpoint: This is Mercury's most powerful endpoint, designed for external platform integrations. It automatically handles persona, contact, and conversation creation/updates, then generates AI responses in a single call.
{
"persona": {
"externalId": "sales-alex-v1",
"name": "Sales Assistant Alex",
"data": {
"role": "sales",
"tone": "professional_friendly",
"business_description": "We provide AI-powered conversation solutions for businesses looking to automate customer interactions while maintaining quality and personalization.",
"channel": "sms",
"identity": {
"name": "Alex",
"role": "Sales Representative"
},
"offers": [
{
"title": "Free Consultation",
"description": "30-minute strategy session",
"value_proposition": "Personalized insights"
},
{
"title": "Product Demo",
"description": "Live platform demonstration",
"value_proposition": "See our solution in action"
}
],
"objections": [
{
"objection": "too expensive",
"response": "I understand budget is important. Let's explore flexible pricing options that provide strong ROI."
},
{
"objection": "need to think about it",
"response": "Absolutely! What specific aspects would help with your decision? I can provide additional information."
}
]
}
},
"contact": {
"externalId": "crm_lead_12345",
"name": "Sarah Johnson",
"data": {
"email": "sarah@techcorp.com",
"phone": "+1234567890",
"company": "TechCorp Inc",
"title": "Marketing Director",
"lead_source": "website_form",
"lead_score": 85,
"interests": ["automation", "customer_service"]
}
},
"conversation": {
"externalId": "conv_techcorp_sarah_website",
"channel": "sms",
"data": {
"campaign": "q1_2024_website_leads",
"priority": "high"
}
},
"message": {
"content": "Hi! I saw your AI conversation platform and I'm interested in learning how it could help us automate our customer support. Can you tell me more about implementation timelines?",
"sender": "contact",
"data": {
"source": "website_form",
"form_data": {
"interest": "customer_support_automation",
"company_size": "50-100_employees",
"current_solution": "zendesk"
}
}
}
}{
"conversation": {
"id": "uuid-conv-123",
"externalId": "conv_techcorp_sarah_website",
"personaId": "uuid-persona-456",
"contactId": "uuid-contact-789",
"channel": "sms",
"messageCount": 2,
"createdAt": "2024-01-15T10:30:00Z",
"updatedAt": "2024-01-15T10:30:15Z"
},
"persona": {
"id": "uuid-persona-456",
"externalId": "sales-alex-v1",
"name": "Sales Assistant Alex",
"data": {
"role": "sales",
"tone": "professional_friendly"
},
"wasCreated": false,
"wasUpdated": true
},
"contact": {
"id": "uuid-contact-789",
"externalId": "crm_lead_12345",
"name": "Sarah Johnson",
"data": {
"email": "sarah@techcorp.com",
"company": "TechCorp Inc"
},
"wasCreated": true,
"wasUpdated": false
},
"messages": [
{
"id": "uuid-msg-001",
"conversationId": "uuid-conv-123",
"content": "Hi! I saw your AI conversation platform and I'm interested in learning how it could help us automate our customer support. Can you tell me more about implementation timelines?",
"sender": "contact",
"data": {
"source": "website_form"
},
"createdAt": "2024-01-15T10:30:00Z"
},
{
"id": "uuid-msg-002",
"conversationId": "uuid-conv-123",
"content": "Hello Sarah! Thanks for your interest in our AI conversation platform. I'd be happy to help you understand how we can streamline your customer support automation.\n\nFor a company like TechCorp with 50-100 employees transitioning from Zendesk, our typical implementation timeline is 2-3 weeks, including:\n\nā¢ Initial setup and configuration (3-5 days)\nā¢ Integration with your existing systems (5-7 days)\nā¢ Team training and testing (3-5 days)\nā¢ Go-live support\n\nGiven your focus on customer support automation, I'd love to show you our live demo that demonstrates how we've helped similar companies reduce response times by 60% while maintaining quality.\n\nWould you be interested in a 30-minute consultation this week to discuss your specific requirements and see the platform in action?",
"sender": "persona",
"data": {
"generated": true,
"confidence": 0.92,
"contextUsed": [
"contact_company_info",
"current_solution",
"implementation_timeline_inquiry"
]
},
"createdAt": "2024-01-15T10:30:15Z"
}
]
}For simpler integrations, you can provide minimal information. Mercury will use sensible defaults and existing data where available.
{
"persona": {
"externalId": "support-bot-v1"
},
"contact": {
"externalId": "customer_456",
"name": "John Smith"
},
"conversation": {
"externalId": "conv_support_john_456",
"channel": "email"
},
"message": {
"content": "My order #12345 hasn't arrived yet. Can you help?",
"sender": "contact"
}
}{
"conversation": { ... },
"persona": {
"id": "uuid-persona-789",
"externalId": "support-bot-v1",
"name": "Customer Support Bot",
"wasCreated": false,
"wasUpdated": false
},
"contact": {
"id": "uuid-contact-012",
"externalId": "customer_456",
"name": "John Smith",
"wasCreated": true,
"wasUpdated": false
},
"messages": [
{
"content": "My order #12345 hasn't arrived yet. Can you help?",
"sender": "contact"
},
{
"content": "I'd be happy to help you track your order #12345, John. Let me look that up for you right away and provide you with the current status and expected delivery information.",
"sender": "persona",
"data": {
"generated": true,
"confidence": 0.88
}
}
]
}{
"error": "Validation failed",
"code": "VALIDATION_ERROR",
"details": {
"field": "persona.externalId",
"message": "External ID is required for persona upsert"
}
}{
"error": "AI response generation failed",
"code": "GENERATION_ERROR",
"details": {
"reason": "Token limit exceeded",
"conversationId": "uuid-conv-123"
},
"conversation": { ... },
"messages": [
{
"content": "User message",
"sender": "contact"
}
]
}Generates AI-powered responses for existing conversations without modifying the conversation history. This endpoint is useful for generating draft responses, A/B testing different responses, or providing response suggestions.
{
"conversationExternalId": "conv_support_sarah_123",
"personaExternalId": "support-specialist-v1",
"context": {
"urgency": "high",
"customerTier": "premium",
"previousIssues": [
{
"issueId": "ISSUE-001",
"type": "billing_question",
"resolved": true
}
]
},
"constraints": {
"maxLength": 300,
"tone": "empathetic_urgent",
"includeNextSteps": true
}
}{
"generatedMessage": {
"content": "I understand this is urgent, Sarah, and I apologize for the inconvenience. Since you're one of our premium customers and I see you had a billing question resolved recently, I want to make sure we address this quickly and thoroughly.\n\nNext steps:\n1. I'm escalating this to our senior technical team\n2. You'll receive an update within 2 hours\n3. I'll personally follow up to ensure resolution\n\nIs there anything else I can clarify in the meantime?",
"confidence": 0.94,
"generationTime": 1.2,
"contextUsed": [
"conversation_history",
"persona_configuration",
"contact_tier_info",
"previous_issue_history"
]
},
"conversation": {
"id": "uuid-conv-456",
"externalId": "conv_support_sarah_123",
"messageCount": 8,
"lastMessageAt": "2024-01-15T14:22:00Z"
},
"persona": {
"id": "uuid-persona-789",
"externalId": "support-specialist-v1",
"name": "Support Specialist Bot"
}
}š” Note: This endpoint generates responses but doesn't add them to the conversation. Use the REST API or the main /conversations RPC endpoint to actually send the generated message.
Executes a specific skill within the context of a conversation, enabling integration with external APIs, data processing, and specialized functionality during conversations.
{
"skillExternalId": "sentiment_analyzer_v1",
"conversationExternalId": "conv_support_john_456",
"input": {
"text": "I'm really frustrated with this service. This is the third time I've had to call about the same issue and nobody seems to be able to help me!",
"includeHistory": true,
"analysisDepth": "detailed"
},
"context": {
"contactId": "customer_789",
"conversationStage": "escalation_review",
"channelType": "phone_call"
}
}{
"execution": {
"id": "exec-uuid-123",
"skillId": "skill-uuid-456",
"conversationId": "conv-uuid-789",
"input": {
"text": "I'm really frustrated...",
"includeHistory": true,
"analysisDepth": "detailed"
},
"output": {
"sentiment": "negative",
"confidence": 0.87,
"emotions": [
{
"emotion": "frustration",
"intensity": 0.92
},
{
"emotion": "disappointment",
"intensity": 0.76
}
],
"escalationRecommended": true,
"priority": "high",
"suggestedActions": [
"immediate_supervisor_escalation",
"customer_retention_alert",
"priority_queue_placement"
]
},
"status": "success",
"executionTime": 0.8,
"createdAt": "2024-01-15T10:30:00Z"
},
"skill": {
"id": "skill-uuid-456",
"externalId": "sentiment_analyzer_v1",
"name": "Advanced Sentiment Analyzer",
"data": {
"role": "sentiment_analysis",
"version": "2.1"
}
},
"conversation": {
"id": "conv-uuid-789",
"externalId": "conv_support_john_456"
}
}{
"skillExternalId": "sentiment_v1",
"conversationExternalId": "conv_123",
"input": {
"text": "Thanks so much! This solved my problem perfectly.",
"analyzeIntensity": true
}
}{
"skillExternalId": "kb_lookup_v1",
"conversationExternalId": "conv_456",
"input": {
"query": "password reset procedure",
"categories": ["account_management"],
"maxResults": 5
}
}{
"skillExternalId": "json_parser_v1",
"conversationExternalId": "conv_789",
"input": {
"jsonData": "{\"order\": {...}}",
"extractFields": ["orderId", "status", "total"],
"validateSchema": true
}
}{
"skillExternalId": "crm_lookup_v1",
"conversationExternalId": "conv_012",
"input": {
"customerId": "CUST-12345",
"fields": ["account_status", "recent_orders"],
"includeNotes": true
}
}ā ļø Legacy Endpoints: These endpoints are maintained for backward compatibility. New integrations should use the modern /conversations RPC endpoint for better functionality and performance.
Legacy endpoint for updating conversation metadata and triggering AI responses.
{
"conversationId": "conv-uuid-123",
"updates": {
"priority": "high",
"tags": ["escalated", "billing"]
},
"generateResponse": true
}{
"conversation": {
"id": "conv-uuid-123",
"priority": "high",
"tags": ["escalated", "billing"],
"updatedAt": "2024-01-15T10:30:00Z"
},
"generatedMessage": {
"content": "I understand this is a priority...",
"createdAt": "2024-01-15T10:30:15Z"
}
}Legacy endpoint for creating individual messages.
{
"conversationId": "conv-uuid-123",
"content": "Thank you for the help!",
"sender": "contact",
"generateResponse": true
}{
"message": {
"id": "msg-uuid-456",
"content": "Thank you for the help!",
"sender": "contact",
"createdAt": "2024-01-15T10:30:00Z"
},
"response": {
"id": "msg-uuid-789",
"content": "You're very welcome! Is there anything else I can help you with today?",
"sender": "persona",
"createdAt": "2024-01-15T10:30:05Z"
}
}