💬 Push Conversations

Import external conversations into LIKE MAGIC unified messaging

This guide walks you through pushing messages from external platforms (website chat, phone calls) into LIKE MAGIC. For the full API specification, see the Unified Messaging API Live Docs.

Required OAuth2 Scopes

Operation	Required Scope
Push messages	`guest.conversation.write`
Read conversations/messages	`guest.conversation.read`

Quick Start

1. Push Messages

Send a POST request with one or more messages. Each message identifies the guest by phone number or email:

curl -X POST \
  '{{monitoringUrl}}/api/unified-messaging-service/guest-conversations/messages' \
  -H 'Authorization: Bearer YOUR_TOKEN' \
  -H 'Content-Type: application/json' \
  -d '{
    "messages": [
      {
        "guestIdentifier": {
          "type": "PHONENUMBER",
          "value": "+41791234567"
        },
        "platform": "WEBSITE_CHAT",
        "direction": "RECEIVED",
        "content": {
          "type": "text",
          "text": {
            "text": "Hi, I would like to book a room for next weekend."
          }
        },
        "messageCreatedAt": "2026-02-10T10:30:00Z"
      },
      {
        "guestIdentifier": {
          "type": "PHONENUMBER",
          "value": "+41791234567"
        },
        "platform": "WEBSITE_CHAT",
        "direction": "SENT",
        "content": {
          "type": "text",
          "text": {
            "text": "Of course! We have availability. Would you like a standard or deluxe room?"
          }
        },
        "messageCreatedAt": "2026-02-10T10:31:00Z"
      }
    ]
  }'

The response returns the created messages with their conversation and message IDs:

[
  {
    "conversationId": "conv-abc123",
    "messageId": "msg-001",
    "direction": "RECEIVED",
    "status": "DELIVERED",
    "communicationChannel": "WEBSITE_CHAT",
    "content": {
      "type": "text",
      "text": { "text": "Hi, I would like to book a room for next weekend." }
    },
    "messageCreatedAt": "2026-02-10T10:30:00Z"
  },
  {
    "conversationId": "conv-abc123",
    "messageId": "msg-002",
    "direction": "SENT",
    "status": "DELIVERED",
    "communicationChannel": "WEBSITE_CHAT",
    "content": {
      "type": "text",
      "text": { "text": "Of course! We have availability. Would you like a standard or deluxe room?" }
    },
    "messageCreatedAt": "2026-02-10T10:31:00Z"
  }
]

2. Retrieve the Conversation

Use the conversationId from the response to fetch the conversation:

curl -X GET \
  '{{monitoringUrl}}/api/unified-messaging-service/guest-conversations/conv-abc123' \
  -H 'Authorization: Bearer YOUR_TOKEN'

3. Retrieve Messages (Paginated)

Fetch messages for a conversation with pagination:

curl -X GET \
  '{{monitoringUrl}}/api/unified-messaging-service/guest-conversations/conv-abc123/messages?page=0&size=20' \
  -H 'Authorization: Bearer YOUR_TOKEN'

Message Format

Guest Identifier

Identify the guest by phone number or email. LIKE MAGIC uses this to match and link conversations to guest profiles.

Type	Format	Example
`PHONENUMBER`	E.164 format	`+41791234567`
`EMAILADDRESS`	Standard email	`guest@example.com`

Content Types

Only text and email content types are supported for push messages.

Text message:

{
  "type": "text",
  "text": { "text": "Your message here" }
}

Email message:

{
  "type": "email",
  "email": {
    "subject": "Booking inquiry",
    "content": {
      "text": "Plain text version",
      "html": "<p>HTML version</p>"
    }
  }
}

Platforms

Platform	Use For
`WEBSITE_CHAT`	Website live chat, chatbot conversations
`PHONE_CALL`	Phone transcripts, IVR interactions, voice bot conversations

Direction

Value	Meaning
`RECEIVED`	Message from the guest to the property
`SENT`	Message from the property to the guest

Constraints

Maximum 100 messages per request
messageCreatedAt must be in the past or present (not future)
pmsPropertyId is optional — defaults to "ACCOUNT" if not provided
Messages for the same guest identifier are grouped into the same conversation

API Reference

For complete API documentation including all endpoints and response schemas:

👉 Unified Messaging API - Live Docs