.. _ai-struct-message:

AI Message
==========

.. _ai-struct-message-message:

Message
-------

.. code::

    {
        "id": "<string>",
        "customer_id": "<string>",
        "aicall_id": "<string>",
        "activeflow_id": "<string>",
        "role": "<string>",
        "content": "<string>",
        "direction": "<string>",
        "tool_calls": [],
        "tool_call_id": "<string>",
        "tm_create": "<string>"
    }

* ``id`` (UUID): The message's unique identifier. Returned when listing via ``GET /ai-messages``.
* ``customer_id`` (UUID): The customer who owns this message. Obtained from the ``id`` field of ``GET /customers``.
* ``aicall_id`` (UUID): The AI call session this message belongs to. Obtained from the ``id`` field of ``GET /aicalls``.
* ``activeflow_id`` (UUID): The ID of the active flow associated with this message. Obtained from the ``id`` field of ``GET /activeflows``. Set to ``00000000-0000-0000-0000-000000000000`` if no active flow.
* ``role`` (enum string): The role of the message sender. See :ref:`Role <ai-struct-message-role>`.
* ``content`` (string): The text content of the message.
* ``direction`` (enum string): The direction of the message. See :ref:`Direction <ai-struct-message-direction>`.
* ``tool_calls`` (array of ToolCall): Tool/function calls requested by the AI assistant. Each entry contains the tool name and arguments. Empty array if no tool calls.
* ``tool_call_id`` (string): The ID of the tool call this message is responding to (for ``tool`` role messages only). Empty string if not a tool response.
* ``tm_create`` (string, ISO 8601): Timestamp when this message was created.

.. _ai-struct-message-role:

Role
----

All possible values for the ``role`` field:

============= ===========
Role          Description
============= ===========
system        A system prompt or instruction
user          A message from the human user (transcribed speech or typed text)
assistant     A response generated by the AI model
function      A function call result (legacy, use ``tool`` instead)
tool          A tool/function call result
notification  A system notification message
============= ===========

.. _ai-struct-message-direction:

Direction
---------

All possible values for the ``direction`` field:

========= ===========
Direction Description
========= ===========
incoming  Message received from the user
outgoing  Message generated by the AI and sent to the user
========= ===========

Example
-------

.. code::

    {
        "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
        "customer_id": "5e4a0680-804e-11ec-8477-2fea5968d85b",
        "aicall_id": "b2c3d4e5-f6a7-8901-bcde-f12345678901",
        "activeflow_id": "c3d4e5f6-a7b8-9012-cdef-123456789012",
        "role": "user",
        "content": "I would like to transfer to the sales department.",
        "direction": "incoming",
        "tool_calls": [],
        "tool_call_id": "",
        "tm_create": "2024-03-01T10:00:05.000000Z"
    }