Interaction
===========

Object Shape
------------

An interaction object will always have this shape when not embedded into other objects:

.. code-block:: json

  {
    "id": "integer",
    "_type": "string",
    "firstDelegate": "object:delegate",
    "secondDelegate": "object:delegate",
    "thirdDelegate": "object:delegate",
    "firstDevice": "object:device",
    "secondDevice": "object:device",
    "thirdDevice": "object:device",
    "interactionType": "string",
    "data": "object",
    "recordedAt": "string",
    "createdAt": "string",
    "updatedAt": "string"
  }

The ``data`` property inside the interaction object does not have a configurable structure and will depend on the type
of interaction. For example a ``lead`` interaction will have all answers loaded in this property.

Interaction Types
-----------------

.. include:: /partial/interactions.rst

GET /interaction/list
---------------------

Get the list of interactions matching the specified query.

.. note::

  This method supports pagination.

  Use limit and offset to paginate returned results. The defaults if no limit or offset are provided are limit=5000 and
  offset=0.

  GET /interaction/list?offset=0&limit=5000

  The total result set count is returned in all responses in the ``meta`` property. Links to the next or previous page
  are also provided in the same property.

POST /interaction/new/{interactionType}
---------------------------------------

Creates a new interaction.

See the list of `Error Responses`_ for more information, in particular error 1301, 1401, 1501, 1502, 1503.

Some examples for common interactions:

.. code-block:: text

  POST /interaction/new/check-in
  POST /interaction/new/join
  POST /interaction/new/lead
  POST /interaction/new/print

Example request to check-in a delegate into a session:

.. code-block:: text

  POST /interaction/new/check-in

.. code-block:: json

  {
    "firstDelegate": 789,
    "firstDevice": 85,
    "recordedAt": 1696185089
  }

Or, because only one delegate and one device are involved:

.. code-block:: json

  {
    "delegate": 789,
    "device": 85,
    "recordedAt": 1696185089
  }

Example response:

.. code-block:: json

  {
    "data": {
      "id": 89027,
      "_type": "interaction",
      "firstDelegate": {
        "id": 789,
        "_type": "delegate"
      },
      "firstDevice": {
        "id": 6,
        "_type": "device"
      },
      "interactionType": "check-in",
      "recordedAt": "2018-03-13T23:31:16+00:00",
      "createdAt": "2018-03-13T23:31:32+00:00",
      "updatedAt": "2018-03-13T23:31:32+00:00"
    },
    "meta": {}
  }

POST /interaction/test/{interactionType}
----------------------------------------

Tests if creating an interaction with the given parameter would succeed or not. This can be used for example to validate
tickets before using them.

See the list of `Error Responses`_ for more information, in particular error 1301, 1401, 1501, 1502, 1503.

Example request to check-in a delegate into a session:

.. code-block:: text

  POST /interaction/test/check-in

.. code-block:: json

  {
    "firstDelegate": 789,
    "firstDevice": 85,
    "recordedAt": 1696185089
  }

Or, because only one delegate and one device are involved:

.. code-block:: json

  {
    "delegate": 789,
    "device": 85,
    "recordedAt": 1696185089
  }

Example response:

.. code-block:: json

  {
    "data": {
      "id": null,
      "_type": "interaction",
      "firstDelegate": {
        "id": 789,
        "_type": "delegate"
      },
      "firstDevice": {
        "id": 6,
        "_type": "device"
      },
      "interactionType": "check-in",
      "recordedAt": "2018-03-13T23:31:16+00:00",
      "createdAt": "2018-03-13T23:31:32+00:00",
      "updatedAt": "2018-03-13T23:31:32+00:00"
    },
    "meta": {}
  }


Example of response in case of failure:

.. code-block:: json

  {
    "data": {},
    "meta": {
      "error": {
        "code": 412,
        "message": "Too many interactions",
        "internalCode": 740
      }
    }
  }

DELETE /interaction/id:{id}
---------------------------

Delete the given interaction. Returns a no content response (status 204).

Example request to delete interaction 123:

.. code-block:: text

  POST /interaction/id:123

POST /interaction/batch
-----------------------

You can send a batch of interaction to this endpoint and they will be processed in order and a ordered collection of
responses will be returned.

See the list of `Error Responses`_ for more information, in particular error 1301, 1401, 1501, 1502, 1503.

Example request:

.. code-block:: text

  POST /interaction/batch

.. code-block:: json

  {
    "interactions": {
      "a": {
        "firstDelegate": 1,
        "interactionType": "upload"
      },
      "b": {
        "firstDelegate": 3,
        "firstDevice": 123,
        "interactionType": "check-in"
      }
    },
    "sharedValues": {
      "upload": "iVBORw0KGgoAA[ ... more base64 encoded stuff ... ]oI5NwAAAABJRU5ErkJggg=="
    }
  }

.. _Error Responses: /rest_api/index.html#error-responses