Skip to content

💡 AI Bot Integration

Important: This documentation describes the integration with our test environment. Before moving to production, please test your integration thoroughly in this environment. Contact api-support@likemagic.tech to get onboarded and receive your test environment credentials.

Mainflow

  • Guest contacts hotel
  • LIKE MAGIC receives incoming message through Bird
  • LIKE MAGIC matches the message to a guest identity and potential existing reservation
  • LIKE MAGIC request an automated answer from the AI partner and provides guest & reservation context
  • AI partner can ask for additional information from the LIKE MAGIC platform if needed (e.g. booked additional services)
  • AI partner provides a response to LIKE MAGIC
  • LIKE MAGIC send the response through Bird to the guest
sequenceDiagram
    participant Bird
    participant "LIKE MAGIC"
    participant "AI partner"

    Bird->>"LIKE MAGIC": 1: Incoming guest message
    activate "LIKE MAGIC"
    "LIKE MAGIC"->>"LIKE MAGIC": 2: Find corresponding guest identity & reservation
    "LIKE MAGIC"->>"AI partner": 3: Guest message with guest identity & reservation context
    activate "AI partner"
    "AI partner"->>"AI partner": 4: Create answer

    opt Fetch additional information
        "AI partner"->>"LIKE MAGIC": 5: Additional information
        "LIKE MAGIC"-->>"AI partner": response
    end

    "AI partner"-->>"LIKE MAGIC": 6: Guest response via Webhook
    deactivate "AI partner"

    "LIKE MAGIC"->>Bird: 7: Respond to guest
    deactivate "LIKE MAGIC"

Information for AI partner

All the events from the AI partner are to be posted (POST) on a webhook provided by LIKE MAGIC.

Whatsapp Number (Test Environment)

+1 (226) 640-5907 (Test environment only - in production you will use the dedicateds number of the hotel)

URL

Environment Endpoint
Test Environment https://monitoring.mews-test.likemagic.tech/api/integration-service/webhook/unified-messaging/mews-test/callback
Test BaseUrl https://monitoring.mews-test.likemagic.tech
Test Tenant likemagic-test

Note: These URLs are for the test environment only. Production URLs will the one of your hotel.

Task API Integration

For the best possible integration experience, we recommend integrating with our Task API. This allows your AI bot to: - Create tasks based on guest requests - Track task status and progress - Handle service requests efficiently - Manage hotel operations seamlessly

For detailed Task API documentation and integration guidelines, refer to our Manage Tasks Guide.

Security

All incoming webhooks are secured with a lm-webhook-secret header. Contact api-support@likemagic.tech to get your test environment secret key.

AI Events description

Property Type Contract Description
event Enum required Defines the type of the event ai.response
conversationId UUID optional Required for type ai.response, ai.action Is shared by LM when receiving the initial guest message
messageId UUID optional Required for type ai.response Unique identifier defined by the AI partner, e.g. 42827c8e-0354-4b13-9319-5093b83886fe
type Enum required Defines in more detail the event
content Object optional Required for type ai.response Answer from the AI partner. The content of this object is dynamic and depends on the type of the message.

AI Message Response

A response from the AI to be sent to the guest.

{
    "event": "ai.response",
    "conversationId": "367fecba-bc23-418b-aef2-7943180860d4",
    "messageId": "U-1",
    "type": "text",
    "content": "Chatbot response to the conversation"
}

Sample CURL

curl -X 'POST' \
  'https://monitoring.mews-test.likemagic.tech/api/integration-service/webhook/unified-messaging/mews-test/callback' \
  -H 'accept: */*'
  -H 'Content-Type: application/json' \
  -d '{
    "event": "ai.response",
    "conversationId": "367fecba-bc23-418b-aef2-7943180860d4",
    "messageId": "U-1",
    "type": "text",
    "content": "Chatbot response to the conversation"
}'

Human intervention needed

Informing LM that a human needs to take over the conversation

{
    "event": "ai.action",
    "conversationId": "367fecba-bc23-418b-aef2-7943180860d4",
    "type": "HUMAN_INTERVENTION_NEEDED",
}

Sample CURL

curl -X 'POST' \
  'https://monitoring.mews-test.likemagic.tech/api/integration-service/webhook/unified-messaging/mews-test/callback' \
  -H 'accept: */*'
  -H 'Content-Type: application/json' \
  -d '{
    "event": "ai.action",
    "conversationId": "367fecba-bc23-418b-aef2-7943180860d4",
    "type": "HUMAN_INTERVENTION_NEEDED",
}'

Webhook to be provided by AI Partner

LIKE MAGIC requires the AI partner to provide an webhook endpoint so the partner can consume events from LM.

Please share the URL with your technical contact person from LM

Security

All outgoing webhooks are secured with a lm-webhook-secret header. Please contact your technical contact person from LM to get the secret.

Webhook Description

Property Type Contract Description
event Enum required Defines the type of the event lm.action
type Enum required Defines in more detail the event whatsapp
tenantName String required Name of the LIKE MAGIC customer
conversationId UUID required Required for type whatsapp | HUMAN_TAKE_OVER |AI_TAKE_OVER unique identifier for a conversation which can contain multiple messages
messageId UUID optional Required for type whatsapp unique identifier of the specific message
pmsReservationId String optional Required for type whatsapp If available the linked reservation id from the PMS will be set
pmsPropertyId String optional Required for type whatsapp If available the linked property id from the PMS will be set. If no property id can be determined the field is not sent
content Object optional Required for type whatsapp | sms | booking_dot_com Message of the guest
String required if event = lm.message
Image object required if event =lm.image
File object required if event = lm.file
Notification object required if event = lm.notification
createdAt DateTime String (ISO-8601) required DateTime String when the message was created
guestActor GuestActor object required Guest details

Guest Actor

Property Type Contract Description
guestIdentityId Long optional Unique guest identifier of LIKE MAGIC
firstName String optional First name of guest if available
lastName String optional Last name of guest if available
phone String required Phone number
email String optional Email of guest if available

Image

Property Type Contract Description
mediaUrl String required URL of the image, to be fetched from LM
caption String optional Optional caption provided by the guest

File

Property Type Contract Description
mediaUrl String required URL of the file, to be fetched from LM
contentType String required File contentType e.g. video/mp4
caption String optional Optional caption provided by the guest

Notification

Property Type Contract Description
text String required Text of the trigger based template message
templateName Enum required Name of the LIKE MAGIC template: COMPANION_ADDED, PRE_CHECKIN_REMINDER, RESERVATION_CREATED, CHECKIN, CHECKED_IN, CHECKIN_INTRODUCTION, CHECKIN_REMINDER, CHECKOUT_ALERT, CHECKOUT_FOLLOW_UP, CHECKOUT_INTRODUCTION, ID_CHECK_DECLINED, INVOICE, RESERVATION_CANCELED
language Enum required Language used of the template, e.g. DE or EN

Guest message

Message of a guest

{
  "event": "lm.message",
  "type": "whatsapp",
  "tenantName": "LIKE MAGIC",
  "conversationId": "CONVERSATION_ID_LIKEMAGIC",
  "messageId": "MESSAGE_ID_LIKEMAGIC",
  "pmsReservationId": "PMS_RESERVATION_ID",
  "pmsPropertyId": "PMS_PROPERTY_ID",
  "content": "An incomming message from a guest",
  "createdAt": "2025-01-14T15:55:59.547Z",
  "guestActor": {
      "guestIdentityId": 12345,
      "firstName": "John",
      "lastName": "Smith",
      "email": "john.smith@example.com",
      "phone": "+15550100000"
  }
}

Sample CURL

curl -X 'POST' \
  'https://AI_PARTNER_URL/webhook' \
  -H 'accept: */*'
  -H 'Content-Type: application/json' \
  -d '{
    "event": "lm.message",
    "type": "whatsapp",
    "tenantName": "LIKE MAGIC"
    "conversationId": "CONVERSATION_ID_LIKEMAGIC",
    "messageId": "MESSAGE_ID_LIKEMAGIC",
    "pmsReservationId": "PMS_RESERVATION_ID",
    "pmsPropertyId": "PMS_PROPERTY_ID",
    "content": "An incomming message from a guest",
    "createdAt": "2025-01-14T15:55:59.547Z",
    "guestActor": {
      "guestIdentityId": 12345,
      "firstName": "John",
      "lastName": "Smith",
      "email": "john.smith@example.com",
      "phone": "+15550100000"
  }
}'

Guest image

Message of a guest containing an image.

{
  "event": "lm.image",
  "type": "whatsapp",
  "tenantName": "LIKE MAGIC",
  "conversationId": "CONVERSATION_ID_LIKEMAGIC",
  "messageId": "MESSAGE_ID_LIKEMAGIC",
  "pmsReservationId": "PMS_RESERVATION_ID",
  "pmsPropertyId": "PMS_PROPERTY_ID",
  "content": {
    "mediaUrl": "https://media.likemagic.tech/VgYYE0oT",
    "caption": "Image caption"
  },
  "createdAt": "2025-01-14T15:55:59.547Z",
  "guestActor": {
      "guestIdentityId": 12345,
      "firstName": "John",
      "lastName": "Smith",
      "email": "john.smith@example.com",
      "phone": "+15550100000"
  }
}

Guest file

Message of a guest containing a file. Check the contentType to understand the file Type

The contentType can be

  • video/mp4
  • audio/ogg
  • application/pdf and more
{
  "event": "lm.file",
  "type": "whatsapp",
  "tenantName": "LIKE MAGIC",
  "conversationId": "CONVERSATION_ID_LIKEMAGIC",
  "messageId": "MESSAGE_ID_LIKEMAGIC",
  "pmsReservationId": "PMS_RESERVATION_ID",
  "pmsPropertyId": "PMS_PROPERTY_ID",
  "content": {
    "mediaUrl": "https://media.likemagic.tech/VgYYE0oT",
    "contentType": "video/mp4",
    "caption": "File caption"
  },
  "createdAt": "2025-01-14T15:55:59.547Z",
  "guestActor": {
      "guestIdentityId": 12345,
      "firstName": "John",
      "lastName": "Smith",
      "email": "john.smith@example.com",
      "phone": "+15550100000"
  }
}

Fetching data from LM based on mediaUrl

To fetch information based on the mediaUrl in the test environment, the AI partner must call:

GET https://monitoring.mews-test.likemagic.tech/api/unified-messaging/guest-conversations/attachments?mediaUrl={mediaUrl}

API Reference

For complete API documentation including all endpoints, request/response schemas and interactive testing:

👉 Unified Messaging API - Live Docs

Trigger based LIKE MAGIC notification

If you are interest in LIKE MAGICs' trigger based configuration please consume the lm.notification events. These contain the content of the templates used with the guest.

{
  "event": "lm.notification",
  "type": "whatsapp",
  "tenantName": "LIKE MAGIC",
  "conversationId": "CONVERSATION_ID_LIKEMAGIC",
  "messageId": "MESSAGE_ID_LIKEMAGIC",
  "pmsReservationId": "PMS_RESERVATION_ID",
  "pmsPropertyId": "PMS_PROPERTY_ID",
  "content": {
    "text": "Hey John🙌\nGrossartig, du bist nun Teil der LIKE MAGIC Familie!🎉\nMit unserer Mobile-Check-in Lösung hast du deinen Aufenthalt in der eigenen Hand. Keine langwierigen Prozesse mehr",
    "templateName"="CHECKIN_REMINDER", 
    "language"="DE"
  },
  "createdAt": "2025-08-19T03:36:11.344091Z",
  "guestActor": {
      "guestIdentityId": 12345,
      "firstName": "John",
      "lastName": "Smith", 
      "email": "john.smith@example.com",
      "phone": "+15550100000"
  }
}

Sample CURL

curl -X 'POST' \
  'https://AI_PARTNER_URL/webhook' \
  -H 'accept: */*'
  -H 'Content-Type: application/json' \
  -d '{
    "event": "lm.notification",
    "type": "whatsapp",
    "tenantName": "LIKE MAGIC"
    "conversationId": "CONVERSATION_ID_LIKEMAGIC",
    "messageId": "MESSAGE_ID_LIKEMAGIC",
    "pmsReservationId": "PMS_RESERVATION_ID",
    "pmsPropertyId": "PMS_PROPERTY_ID",
    "content": {
      "text": "A template based notification",
      "templateName"="CHECKIN_REMINDER", 
      "language"="DE"
    },
    "createdAt": "2025-01-14T15:55:59.547Z",
    "guestActor": {
      "guestIdentityId": 12345,
      "firstName": "John",
      "lastName": "Smith",
      "email": "john.smith@example.com",
      "phone": "+15550100000"
  }
}'

Message interaction

LM informs the AI partner that an interaction with a message happened

{
  "event": "lm.message.interaction",
  "type": "read",
  "tenantName": "LIKE MAGIC"
  "messageId": "MESSAGE_ID_LIKEMAGIC",
  "pmsPropertyId": "PMS_PROPERTY_ID",
  "conversationId": "CONVERSATION_ID_LIKEMAGIC"
}

Sample CURL

curl -X 'POST' \
  'https://AI_PARTNER_URL/webhook' \
  -H 'accept: */*'
  -H 'Content-Type: application/json' \
  -d '{
    "event": "lm.message.interaction",
    "type": "read",
    "tenantName": "LIKE MAGIC"
    "messageId": "MESSAGE_ID_LIKEMAGIC",
    "pmsPropertyId": "PMS_PROPERTY_ID",
    "conversationId": "CONVERSATION_ID_LIKEMAGIC"
}'

Human take over

LM informs the AI partner that the conversation is taken over by a human

{
  "event": "lm.action",
  "type": "HUMAN_TAKE_OVER",
  "tenantName": "LIKE MAGIC"
  "pmsPropertyId": "PMS_PROPERTY_ID",
  "conversationId": "CONVERSATION_ID_LIKEMAGIC"
}

Sample CURL

curl -X 'POST' \
  'https://AI_PARTNER_URL/webhook' \
  -H 'accept: */*'
  -H 'Content-Type: application/json' \
  -d '{
    "event": "lm.action",
    "type": "HUMAN_TAKE_OVER",
    "tenantName": "LIKE MAGIC"
    "pmsPropertyId": "PMS_PROPERTY_ID",
    "conversationId": "CONVERSATION_ID_LIKEMAGIC"
}'

AI take over

LM informs the AI partner that the conversation should be taken over by them

{
  "event": "lm.action",
  "type": "AI_TAKE_OVER",
  "tenantName": "LIKE MAGIC"
  "pmsPropertyId": "PMS_PROPERTY_ID",
  "conversationId": "CONVERSATION_ID_LIKEMAGIC"
}

Sample CURL

curl -X 'POST' \
  'https://AI_PARTNER_URL/webhook' \
  -H 'accept: */*'
  -H 'Content-Type: application/json' \
  -d '{
    "event": "lm.action",
    "type": "AI_TAKE_OVER",
    "tenantName": "LIKE MAGIC"
    "pmsPropertyId": "PMS_PROPERTY_ID",
    "conversationId": "CONVERSATION_ID_LIKEMAGIC"
}'

Interacting with a guest-conversation

We provide option to do following changes to a guest-conversation

  • resolve a conversation
  • change the associated pmsPropertyId

both endpoints return the current guest conversation object.

API Reference

For complete API documentation including all endpoints, request/response schemas and interactive testing:

👉 Unified Messaging API - Live Docs

Integration Certification

Before moving your integration to production, you'll need to complete a certification process with LIKE MAGIC. This ensures your integration meets our quality standards and follows best practices.

Certification Process

  1. Complete your integration development and testing in the test environment
  2. Ensure all required endpoints are implemented and working correctly
  3. Verify error handling and edge cases are properly managed
  4. Test all message types and interactions thoroughly

Schedule Certification Call

When you're ready to certify your integration: 1. Email api-support@likemagic.tech with subject "Integration Certification Request" 2. Include your test environment tenant name and a brief summary of your integration and the supported use cases 3. Provide your availability for a certification call 4. Our team will review your integration and schedule a certification meeting

During the certification call, we'll verify your integration's functionality and provide any necessary feedback before approving it for production use.