.. _common-struct-address:

Address
=======

.. _common-struct-address-address:

Address
-------
Defines source/destination address. This structure is used throughout VoIPBin wherever communication endpoints are specified, including calls (``POST /calls``), messages (``POST /messages``), flows (connect/call actions), and number configurations.

.. code::

    {
        "type": "<string>",
        "target": "<string>",
        "target_name": "<string>",
        "name": "<string>",
        "detail": "<string>"
    }

* ``type`` (enum string): Address type. Determines how ``target`` is interpreted. See :ref:`Type <common-struct-address-type>`.
* ``target`` (String): The address endpoint. Format depends on ``type``: E.164 phone number for ``tel`` (e.g., ``+15551234567``), extension number for ``extension`` (e.g., ``2001``), agent UUID for ``agent`` (obtained from ``GET /agents``), SIP URI for ``sip`` (e.g., ``user@domain.com``), WhatsApp phone number for ``whatsapp``, webchat widget UUID for ``webchat``, or webchat session UUID for ``web_session``.
* ``target_name`` (String): Display name associated with the address. For ``tel`` type, this is the caller ID name. Optional. **For ``extension`` type, this is the routing key** and must be set to the target extension's ``extension`` (username) field, not its ``name`` (display label) field. See :ref:`Extension <extension-struct-extension-extension>`.
* ``name`` (String): A human-readable label for this address. Optional.
* ``detail`` (String): Additional description or metadata for this address. Optional.

.. note:: **AI Implementation Hint**

   When constructing an Address, only ``type`` and ``target`` are required. For ``tel`` type, the ``target`` must be in E.164 format with a leading ``+`` and no spaces or special characters. For ``agent`` type, the ``target`` must be a valid agent UUID obtained from ``GET /agents``.

Example
+++++++

* The ``tel`` type address. The target is a phone number in E.164 format.

.. code::

  {
    "type": "tel",
    "target": "+821100000001"
  }

* The ``extension`` type address. The target is an extension number.

.. code::

  {
    "type": "extension",
    "target": "2001"
  }

* The ``agent`` type address. The target is the agent's UUID, obtained from ``GET /agents``.

.. code::

  {
    "type": "agent",
    "target": "eed6a98a-f18d-11ee-96d3-133e13eafff9"
  }

* The ``sip`` type address. The target is a SIP URI.

.. code::

  {
    "type": "sip",
    "target": "testuser@example.com"
  }


.. _common-struct-address-type:

Type
------------
Defines types of address.

=========== =====================================================================
Type        Description
=========== =====================================================================
agent       Address for calling an agent. ``target`` must be the agent's UUID, obtained from ``GET /agents``.
ai          Address for an AI resource. ``target`` must be the AI resource's UUID.
ai_team     Address for an AI team. ``target`` must be the AI team's UUID.
conference  Address for a conference. ``target`` must be the conference's UUID, obtained from ``GET /conferences``.
email       Address for email. ``target`` must be a valid email address (e.g., ``user@example.com``).
extension   Address for calling an extension number. ``target`` is the extension number string (e.g., ``2001``). ``target_name`` must be the extension's ``extension`` (username) field, not its ``name`` (display label) field; a mismatched value causes the call request to fail.
line        Line type address. Used for LINE messaging integrations. ``target`` is the LINE user or channel ID.
sip         SIP protocol address. ``target`` is a SIP URI (e.g., ``user@domain.com``).
tel         Telephone number address. ``target`` must be in E.164 format (e.g., ``+15551234567``).
webchat     Address for a webchat widget (the customer/agent side of a webchat conversation). ``target`` is the webchat widget's UUID.
web_session Address for a webchat visitor session (the visitor side of a webchat conversation). ``target`` is the webchat session's UUID -- the visitor's continuity token.
whatsapp    Address for a WhatsApp conversation. ``target`` is the WhatsApp phone number.
=========== =====================================================================