The POST /conversations RPC endpoint provides advanced conversation management through resource upserts. Unlike REST endpoints, this RPC call can create or update conversations, contacts, and personas in a single atomic operation, making it ideal for streamlined workflow integrations.
POST https://your-api-name.mercury.ratiomachina.com/conversations Content-Type: application/json Authorization: x-mercury-api-key: YOUR_API_KEY
Create or update a conversation with minimal payload. Ideal for simple conversation management scenarios.
{
"operation": "upsert_conversation",
"conversation": {
"external_id": "crm-lead-john-smith-001",
"persona": {
"external_id": "sales-assistant-v2"
},
"contact": {
"external_id": "lead-john-smith",
"name": "John Smith",
"email": "john.smith@techcorp.com"
},
"data": {
"channel": "email",
"priority": "high",
"lead_source": "website_signup",
"product_interest": "enterprise_solution"
},
"status": "active",
"tags": ["enterprise", "qualified_lead", "hot_prospect"]
}
}{
"operation_result": {
"operation": "upsert_conversation",
"status": "success",
"processing_time_ms": 850
},
"conversation": {
"id": "uuid-conv-123",
"external_id": "crm-lead-john-smith-001",
"persona_id": "uuid-persona-456",
"contact_id": "uuid-contact-789",
"status": "active",
"created": true,
"updated_fields": []
},
"related_resources": {
"contact": {
"id": "uuid-contact-789",
"external_id": "lead-john-smith",
"created": false,
"updated": true,
"updated_fields": ["email"]
},
"persona": {
"id": "uuid-persona-456",
"external_id": "sales-assistant-v2",
"found": true
}
}
}{
"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
}{
"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"
}
}{
"operation_result": {
"operation": "upsert_conversation",
"status": "failed",
"processing_time_ms": 450,
"error_code": "VALIDATION_FAILED"
},
"errors": [
{
"type": "validation_error",
"field": "conversation.persona.external_id",
"message": "Referenced persona 'non-existent-persona' not found",
"code": "RESOURCE_NOT_FOUND"
},
{
"type": "data_error",
"field": "conversation.contact.email",
"message": "Invalid email format",
"code": "INVALID_FORMAT"
}
],
"warnings": [
{
"type": "performance_warning",
"message": "Large number of initial messages may impact performance",
"code": "PERFORMANCE_WARNING"
}
],
"validation_details": {
"persona_exists": false,
"contact_valid": false,
"conversation_valid": true
}
}