Applied LabsDocs
Messages

Create message

Create an inbound customer message. If `conversation.id` is provided the message is appended to that conversation; otherwise a new conversation is created on the channel given by `conversation.type` (email / sms / web_chat). For email, threading uses RFC 5322 References / In-Reply-To headers passed via `message.email`. The AI agent processes the message and any reply is delivered through Applied's native channel (Postmark for email, Twilio for SMS, WebSocket for web chat) — never through a ticketing connector.

POST/v2026-04/messages/

Usage

Start from this cURL example and add filters as needed.

cURL
curl -X POST https://core.appliedlabs.ai/v2026-04/messages/ \
  -H "Authorization: Bearer <api-token>" \
  -H "X-Shop-Id: 66e4c4d2-34e8-4f85-8f51-84b6ed7b5f10" \
  -H "Content-Type: application/json" \
  --data '{
  "contact": {
    "email": "support@example.com",
    "name": "",
    "phone": "string",
    "remote_id": "string"
  },
  "conversation": {
    "agent_contact": "string",
    "direction": "inbound",
    "flags": [
      "66e4c4d2-34e8-4f85-8f51-84b6ed7b5f10"
    ],
    "id": "66e4c4d2-34e8-4f85-8f51-84b6ed7b5f10",
    "intent_id": "66e4c4d2-34e8-4f85-8f51-84b6ed7b5f10",
    "tags": [
      "string"
    ],
    "topic_id": "66e4c4d2-34e8-4f85-8f51-84b6ed7b5f10",
    "type": "email",
    "user_id": "66e4c4d2-34e8-4f85-8f51-84b6ed7b5f10"
  },
  "message": {
    "attachments": [
      "66e4c4d2-34e8-4f85-8f51-84b6ed7b5f10"
    ],
    "content": "string",
    "email": {
      "bcc": [
        {
          "email": "support@example.com",
          "name": ""
        }
      ],
      "cc": [
        {
          "email": "support@example.com",
          "name": ""
        }
      ],
      "in_reply_to": "",
      "references": [
        "string"
      ],
      "subject": ""
    },
    "format": "TEXT",
    "remote_id": "string",
    "timestamp": "2026-04-07T14:30:00Z"
  }
}'

Authorizations

Authorizationstringheaderrequired

Send your Applied API key as Authorization: Bearer AL.... Create the key in the Applied dashboard and keep it on your server.

Header parameters

X-Shop-Idstring · uuidrequired

The shop whose data you want to read.

Body

required
contactobjectrequired
contact.emailstring · email | null
contact.namestring
contact.phonestring | null
contact.remote_idstring | null

Your system's stable ID for this customer. Stored on the contact with the platform set to your workspace handle, and used to match the same customer on future messages even if their email or phone changes.

conversationobjectrequired
conversation.agent_contactstring | null

The support email or phone the inbound message was sent to. Used to resolve which Agent handles the conversation. Required for email and sms types; omit for web_chat.

conversation.directionenum<string>required
inbound
conversation.flagsarray | null

IDs of flags to apply to the conversation before the AI agent processes the message. Appended to any flags already on the conversation; duplicates are ignored. Adding a flag triggers any flows configured for it. At most 10 per request.

conversation.idstring · uuid | null
conversation.intent_idstring · uuid | null
conversation.tagsarray | null

Tags to apply to the conversation before the AI agent processes the message. Appended to any tags already on the conversation; duplicates are ignored. At most 20 per request.

conversation.topic_idstring · uuid | null
conversation.typeoneOf
emailsmsweb_chat
conversation.user_idstring · uuid | null
messageobjectrequired
message.attachmentsarray
message.contentstringrequired
message.emailobject

Optional email-specific headers attached to message.email.

message.formatallOf
TEXTMARKDOWNHTML
message.remote_idstring | null
message.timestampstring · date-time | null
Generated Exampleapplication/json
{
  "contact": {
    "email": "support@example.com",
    "name": "",
    "phone": "string",
    "remote_id": "string"
  },
  "conversation": {
    "agent_contact": "string",
    "direction": "inbound",
    "flags": [
      "66e4c4d2-34e8-4f85-8f51-84b6ed7b5f10"
    ],
    "id": "66e4c4d2-34e8-4f85-8f51-84b6ed7b5f10",
    "intent_id": "66e4c4d2-34e8-4f85-8f51-84b6ed7b5f10",
    "tags": [
      "string"
    ],
    "topic_id": "66e4c4d2-34e8-4f85-8f51-84b6ed7b5f10",
    "type": "email",
    "user_id": "66e4c4d2-34e8-4f85-8f51-84b6ed7b5f10"
  },
  "message": {
    "attachments": [
      "66e4c4d2-34e8-4f85-8f51-84b6ed7b5f10"
    ],
    "content": "string",
    "email": {
      "bcc": [
        {
          "email": "support@example.com",
          "name": ""
        }
      ],
      "cc": [
        {
          "email": "support@example.com",
          "name": ""
        }
      ],
      "in_reply_to": "",
      "references": [
        "string"
      ],
      "subject": ""
    },
    "format": "TEXT",
    "remote_id": "string",
    "timestamp": "2026-04-07T14:30:00Z"
  }
}

Response

The existing message that matched the dedup key.

agent_idstring · uuid | nullrequired
contact_idstring · uuid | nullrequired
contact_remote_idstring | nullrequired

Your system's ID for the message's contact, if one is set.

contentstring
conversation_flagsarrayrequired

IDs of flags currently applied to the message's conversation.

conversation_flags[]string · uuid
conversation_idstring · uuid | nullrequired
conversation_tagsarrayrequired

Tags currently applied to the message's conversation.

conversation_tags[]string
created_atstring · date-time
formatenum<string>

How the message content is formatted.

TEXTRICH_TEXTHTMLMARKDOWN
idstring · uuidrequired
remote_idstring | null
remote_platformstring | null
rolestring
statusoneOf

Delivery status for outbound messages.

PENDINGDELIVEREDFAILEDHIDDEN
textstring
ticket_idstring · uuid | nullrequired
typeenum<string>

Whether the message is customer-facing or internal only.

InternalExternal
updated_atstring · date-timerequired
user_idstring · uuid | nullrequired
{
  "agent_id": "33333333-3333-4333-8333-333333333333",
  "contact_id": "11111111-1111-4111-8111-111111111111",
  "contact_remote_id": "cus_3667beus",
  "content": "Participant individual American range attorney role.",
  "conversation_flags": [
    "aaaaaaaa-aaaa-4aaa-8aaa-aaaaaaaaaaaa"
  ],
  "conversation_id": "55555555-5555-4555-8555-555555555555",
  "conversation_tags": [
    "vip",
    "billing"
  ],
  "created_at": "2026-04-07T14:30:00Z",
  "format": "TEXT",
  "id": "66666666-6666-4666-8666-666666666666",
  "remote_id": "msg_0426mwfo",
  "remote_platform": "zendesk",
  "role": "assistant",
  "status": "DELIVERED",
  "text": "Participant individual American range attorney role.",
  "ticket_id": "77777777-7777-4777-8777-777777777777",
  "type": "External",
  "updated_at": "2026-04-07T15:12:00Z",
  "user_id": "44444444-4444-4444-8444-444444444444"
}