Ringover Messages API

openapi: 3.2.0
info:
  license:
    name: Proprietary – Contact us for usage terms
    url: https://www.ringover.com/contact
  description: '# Ringover Public API


    Welcome to the Ringover Public API. This RESTful API lets you integrate Ringover telephony, messaging, contacts, and AI analytics into your applications. ## Base URL


    | Region | Base URL |

    |--------|----------|

    | Europe | `https://public-api.ringover.com/v2` |

    | United States | `https://public-api-us.ringover.com/v2` |


    ## Authentication


    All requests must include your API key in the `Authorization` header:


    ```

    Authorization: your-api-key-here

    ```


    To create an API key:

    1. Open the Ringover Dashboard. 2. Navigate to **Developer > API Keys**. 3. Click **Create an API key**, select a user, and set a label. 4. Configure the permissions for this key (see Permissions below). ## Permissions


    Each API key is associated with **7 permission categories**, each configurable as **None**, **Read**, **Write**, or **Read+Write**:


    | Category | Controls access to |

    |----------|-------------------|

    | **Calls** | Call history, archives, live call controls, callbacks |

    | **Contacts** | Contact CRUD and phone number management |

    | **Users** | User listing, plannings, presences, groups, user blacklists |

    | **Numbers** | Phone number listing, team blacklist |

    | **IVRs** | IVR/scenario listing, tag management |

    | **Conversations** | SMS/Chat conversations, messages, SMS sending |

    | **Empower** | AI call analysis, summaries, moments, analytics |


    ### The Monitoring flag (Supervision)


    In addition to R/W permissions, each API key has a **Monitoring** toggle that controls the **scope** of data returned:


    | Monitoring | Effect |

    |------------|--------|

    | **OFF** | Your permissions give access to **your own data only** (your calls, your numbers, your conversations…) |

    | **ON** | Your permissions give access to **the entire team''s data** (all users, all calls, all conversations…) |


    Monitoring does **not** grant additional permissions — it widens the scope of existing ones. Some routes **require** Monitoring to be enabled and will return `401` without it. Conversely, some routes may ignore the Monitoring flag entirely or apply it differently — unless stated otherwise in the endpoint documentation, the default behavior described above applies. > Each endpoint in this documentation specifies its exact permission and monitoring requirements. ### Special cases


    - **Campaigns, Tasks, WhatsApp**: These routes do not require specific token permissions. A valid API key is sufficient. - **Empower**: Uses its own role system (Admin / Supervisor / User) in addition to the Empower R/W permission. - **Transcriptions**: Access is controlled by a team-level setting, not by the token permissions. - **Conferences**: All conference routes require Monitoring enabled. ## Rate Limiting


    A **2-request-per-second** rate limit is applied per API key. Exceeding this limit returns `429 Too Many Requests`. ## Pagination


    List endpoints support offset-based pagination with two parameters:

    - `limit_count`: Maximum number of items to return (default: 100, max varies by endpoint). - `limit_offset`: Number of items to skip (default: 0). Some call-related endpoints also support cursor-based pagination via `last_id_returned`. ## Error Responses


    | HTTP Code | Meaning |

    |-----------|---------|

    | `400` | Bad request — invalid parameters or body |

    | `401` | Unauthorized — invalid/expired API key, or access denied by permission/monitoring checks on most endpoints |

    | `403` | Forbidden — authenticated request refused by specific endpoint logic (notably some Empower routes) or upstream forwarded services |

    | `402` | Payment required — feature not available on your plan |

    | `404` | Resource not found |

    | `429` | Rate limit exceeded |

    | `500` | Internal server error |


    ## SCIM 2.0 Provisioning


    Ringover exposes a **SCIM 2.0** server (RFC 7643 / RFC 7644) for automated user and group provisioning from your identity provider (Okta, Microsoft Entra ID, …). It reuses the **same API key** as the REST API (`Authorization` header).'
  version: 2.1.0
  title: Ringover Public Messages API
  x-logo:
    url: https://webcdn.ringover.com/app/img/misc/logo_app_redoc.png
    backgroundColor: '#FAFAFA'
    altText: Ringover Logo
  termsOfService: https://ringover.com/terms/
  contact:
    email: support@ringover.com
servers:
- url: https://public-api.ringover.com/v2
  description: Production server (Europe)
- url: https://public-api-us.ringover.com/v2
  description: Production server (United States)
security:
- Authorization: []
tags:
- name: Messages
  description: 'Manage messages within conversations. List messages, archive and unarchive individual messages.


    **Permissions required:**

    - **Read** (`Conversations R`): List messages in a conversation.

    - **Write** (`Conversations W`): Archive/unarchive messages.


    **Monitoring impact:**

    - *OFF*: Returns non-archived messages from your own conversations.

    - *ON*: Returns all messages including archived ones. Enables level-2 archiving (permanent) for messages — requires Monitoring ON.'
paths:
  /conversations/{convId}/messages:
    get:
      operationId: getConversationsConvidMessages
      tags:
      - Messages
      summary: List messages from a conversation
      x-permissions:
        required: Conversations R
        monitoring: optional
        monitoring-off: Returns only non-archived messages.
        monitoring-on: Returns all messages, including archived ones.
      description: 'Returns the first 100 messages in a specific conversation by default. Use `limit_count` and `last_id_returned` to paginate through results.


        **Permission:** `Conversations Read` required.


        **Monitoring:** Optional. With Monitoring **OFF**, only non-archived messages are returned. With Monitoring **ON**, all messages are returned including archived ones (you can also use the `display_archived` parameter).'
      parameters:
      - name: limit_count
        in: query
        description: 'Maximum number of results to return per page. Default: server-defined.'
        schema:
          type: integer
          format: int64
          maximum: 1000
          example: 100
      - name: last_id_returned
        in: query
        description: Last id returned (To avoid duplicates we use it instead of limit_offset)
        schema:
          type: integer
          format: int64
          example: 0
      - name: display_archived
        in: query
        description: A boolean to enable the archive display
        schema:
          type: boolean
          example: false
      - name: convId
        in: path
        description: The conversation ID
        required: true
        schema:
          type: integer
      responses:
        '200':
          description: Successful operation — the message list is returned.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/conversation_message_list'
        '204':
          description: No messages found in this conversation.
        '400':
          description: Invalid query parameters or conversation ID.
        '401':
          description: Unauthorized — missing or invalid API token, or missing `Conversations Read` permission.
        '404':
          description: Conversation not found — no conversation matches the provided ID.
        '500':
          description: Internal server error.
  /conversations/{convId}/messages/{messageId}/archive:
    post:
      tags:
      - Messages
      operationId: conversationPostMessageArchive
      summary: Archive a message (level 1 — soft)
      x-permissions:
        required: Conversations W
        monitoring: none
      description: 'Performs a **level-1 (soft) archive** on a specific message within a conversation. This is a reversible operation — the message can be restored using the `/unarchive` endpoint.


        For permanent deletion, use `DELETE /conversations/{convId}/messages/{messageId}/archive` (level-2 archive), which requires Monitoring to be enabled.


        **Permission:** `Conversations Write` required.


        **Monitoring:** No impact.'
      parameters:
      - name: convId
        in: path
        description: The identifier of the conversation
        required: true
        schema:
          type: integer
          format: int64
          example: 123456
      - name: messageId
        in: path
        description: The identifier of the message
        required: true
        schema:
          type: integer
          format: int64
          example: 123456
      responses:
        '200':
          description: Message successfully archived (level 1 — reversible).
        '400':
          description: Invalid conversation or message ID format.
        '401':
          description: Unauthorized — missing or invalid API token, or missing `Conversations Write` permission.
        '404':
          description: Conversation or message not found.
        '500':
          description: Internal server error.
    delete:
      tags:
      - Messages
      operationId: conversationDeleteMessageArchive
      summary: Permanently archive a message (level 2)
      x-permissions:
        required: Conversations W
        monitoring: required
      description: 'Performs a **level-2 (permanent) archive** on a specific message within a conversation. This operation is **irreversible** and requires Monitoring to be enabled on your API key.


        Unlike level-1 archive (`POST .../archive`), which is soft and reversible via `/unarchive`, level-2 archive permanently removes the message. Returns `401` if Monitoring is OFF.


        **Permission:** `Conversations Write` required.


        **Monitoring:** **Required.** Returns `401` if Monitoring is OFF.'
      parameters:
      - name: convId
        in: path
        description: The conversation ID
        required: true
        schema:
          type: integer
      - name: messageId
        in: path
        description: The message ID
        required: true
        schema:
          type: integer
      responses:
        '200':
          description: Message permanently archived (level 2 — irreversible).
        '400':
          description: Invalid conversation or message ID format.
        '401':
          description: Unauthorized — missing or invalid API token, missing `Conversations Write` permission, or Monitoring is not enabled (required for level-2 archive).
        '404':
          description: Conversation or message not found.
  /conversations/{convId}/messages/{messageId}/unarchive:
    post:
      tags:
      - Messages
      operationId: conversationMessageUnarchive
      summary: Unarchive a message
      x-permissions:
        required: Conversations W
        monitoring: none
      description: 'Restores a previously level-1 archived message. Only messages archived with `POST .../archive` can be unarchived. Level-2 archived messages (via `DELETE`) are permanently removed and cannot be restored.


        **Permission:** `Conversations Write` required.


        **Monitoring:** No impact.'
      parameters:
      - name: convId
        in: path
        description: The identifier of the conversation
        required: true
        schema:
          type: integer
          format: int64
          example: 123456
      - name: messageId
        in: path
        description: The identifier of the message
        required: true
        schema:
          type: integer
          format: int64
          example: 123456
      responses:
        '200':
          description: Message successfully unarchived.
        '400':
          description: Invalid conversation or message ID format.
        '401':
          description: Unauthorized — missing or invalid API token, or missing `Conversations Write` permission.
        '404':
          description: Conversation or message not found, or the message was permanently archived (level 2).
        '500':
          description: Internal server error.
components:
  schemas:
    user_light:
      type: object
      properties:
        user_id:
          type: integer
          format: int64
          description: The user identifier
          example: 123456
        team_id:
          type: integer
          format: int64
          description: The team identifier of the user
          example: 123456
        initial:
          type: string
          description: The initials of the user
          example: PM
        color:
          type: string
          example: 3CC8C8
        firstname:
          type: string
          description: The firstname of the user
          example: Pauline
        lastname:
          type: string
          description: The lastname of the user
          example: Martin
        company:
          type: string
          description: The company of the user
          example: Ringover
        email:
          type: string
          description: The email of the user
          example: pauline.martin@ringover.com
        picture:
          type: string
          description: The picture of the user
          example: https://cdn77.ringover.com/img/users/default.jpg
        concat_name:
          type: string
          example: Pauline Martin
    contact:
      type: object
      properties:
        contact_id:
          type: integer
          format: int64
          example: 654321
        is_shared:
          type: boolean
          example: true
        im_owner:
          type: string
        social_service:
          type:
          - string
          - 'null'
          example: null
        social_service_id:
          type: string
          example: 00P7U000015Ei75YBX
        social_profile_url:
          type:
          - string
          - 'null'
          example: null
        social_data:
          type:
          - string
          - 'null'
          example: null
        firstname:
          type: string
          example: John
        lastname:
          type: string
          example: Do
        company:
          type: string
          example: DoeCompany
        concat_name:
          type: string
          example: John Doe
        color:
          type: string
          example: 3CC8C8
        initial:
          type: string
          example: JD
        profile_picture:
          type:
          - string
          - 'null'
          example: null
        creation_date:
          type: string
          format: date-time
          example: '2018-08-12T12:12:40.53Z'
        numbers:
          type:
          - array
          - 'null'
          items:
            type: integer
            format: uint64
            example: 331797500010
    message:
      type: object
      properties:
        message_id:
          type: integer
          format: int64
          example: 11223344
        mdr_uuid:
          type: string
          description: is displayed for external conversations
        thread:
          type: object
          properties:
            thread_uuid:
              type: string
            conversation_id_linked:
              type: integer
            conversation_sms_id_linked:
              type: integer
            nb_response:
              type: integer
            buffer_section:
              type: integer
        conversation_id:
          type: integer
        conversation_user_id:
          type: integer
        user:
          $ref: '#/components/schemas/user_light'
        contact:
          $ref: '#/components/schemas/contact'
        number:
          $ref: '#/components/schemas/format_number'
        buffer:
          type: string
          example: Hello World
          description: Content of the message
        total_price:
          type: integer
          description: Is `null` if the conversation is internal
        total_plan:
          type: integer
          description: Is `null` if the conversation is internal
        is_failed:
          type: boolean
          example: false
        nb_fragments:
          type: integer
          description: Depends on the number of characters sent
        direction:
          type:
          - string
          - 'null'
          enum:
          - IN
          - OUT
          example: IN
        is_archived:
          type: boolean
          example: false
        archive_date:
          type: string
          format: date-time
          example: '2019-03-11T12:20:50.52Z'
        creation_date:
          type: string
          format: date-time
          example: '2018-12-21T12:20:50.52Z'
        update_date:
          type: string
          format: date-time
          example: '2018-12-21T12:20:50.52Z'
    conversation_message_list:
      type: object
      properties:
        conversation_id:
          type: integer
          format: int64
          example: 222111
        is_sms_write:
          type: boolean
          example: false
          description: Allows to send SMS
        type:
          type: string
          enum:
          - INTERNAL
          - EXTERNAL
          - COLLABORATIVE
          example: INTERNAL
        name:
          type: string
          example: My favorite conversation
        purpose:
          type: string
          example: Description of my favorite conversation
        unread_messages_count:
          type: integer
          format: int64
        last_id_returned_setted:
          type: integer
          format: int64
          example: 0
        limit_count_setted:
          type: integer
          format: int64
          example: 1
        total_messages_count:
          type: integer
          format: int64
          example: 8
        message_list_count:
          type: integer
          format: int64
          example: 54
        message_list:
          type: array
          items:
            $ref: '#/components/schemas/message'
        is_archived:
          type: boolean
          example: false
          description: Archived flag
        creation_date:
          type: string
          format: date-time
          example: '2018-06-12T23:23:40.99Z'
        update_date:
          type: string
          format: date-time
          example: '2019-02-12T12:20:50.52Z'
    format_number:
      type: object
      properties:
        raw:
          type: integer
          format: int64
          example: 184800000
        country_code:
          type: string
          example: '33'
        country:
          type: string
          example: FR
        e164:
          type: string
          example: '+33184800000'
        international:
          type: string
          example: +33 1 84 80 00 00
        international_alt:
          type: string
          example: '33184800000'
        national:
          type: string
          example: 01 84 80 00 00
        national_alt:
          type: string
          example: 0184800000
        rfc3966:
          type: string
          example: tel:+33-1-84-80-00-00
        is_short_code:
          type: boolean
          example: false
  securitySchemes:
    Authorization:
      description: "We use API keys for authentication to authorize API requests. First, you need to create a public access token (API key) and select the appropriate rights for each user. To do so:\n  1. Open the Ringover Dashboard.\n  2. Go to the **Developer** section.\n  3. Click the **Create an API key** button.\n  4. Select a user in the drop-down menu and enter a label for the key and click the **Create** button.\n  5. Click the **Edit** button corresponding to the API key and select the appropriate rights.\n\nOnce you've created a public access token, you can use it in the `Authorization` header to authenticate your HTTP request.\n\n```\nAuthorization: <your-public-token>\n```\n\nThis is the **recommended authentication method** and the only one supported by the REST and SCIM endpoints.\n"
      type: apiKey
      name: Authorization
      in: header
    AuthorizationQuery:
      description: '**Alternative authentication method, only available on the MCP endpoint (`/mcp`).**


        Pass your Public API token via the `token` query string parameter:


        ```

        POST /mcp?token=<your-public-token>

        ```


        Useful for clients (no-code platforms, browser tools, etc.) that cannot set custom HTTP headers.


        See the **mcp** tag for details on the three accepted authentication sources and their precedence.

        '
      type: apiKey
      name: token
      in: query
    AuthorizationPath:
      description: '**Alternative authentication method, only available on the MCP endpoint (`/mcp/{token}`).**


        Pass your Public API token directly inside the URL path:


        ```

        POST /mcp/<your-public-token>

        ```


        Most permissive variant — works with any HTTP client, including those that strip custom headers and query strings.


        > ⚠️ The token appears in URLs and is therefore likely to be logged by proxies, browsers and access logs. Prefer the `Authorization` header whenever your client supports it, and rotate any token that may have leaked.


        OpenAPI 3.0 does not support `apiKey` in `path`, so this scheme is declared in `query` for tooling compatibility — the actual transport is the URL path. See the **mcp** tag for details.

        '
      type: apiKey
      name: token
      in: query
x-tagGroups:
- name: Ringover Public API
  tags:
  - How to paginate?
  - teams
  - groups
  - users
  - numbers
  - ivrs
  - tags
  - conferences
  - calls
  - campaigns
  - channels
  - contacts
  - conversations
  - messages
  - sms
  - profiles
  - presences
  - blacklist
  - webhook
  - callbacks
  - surveys
  - snoozes
  - transcriptions
  - cdn
  - empower
  - whatsapp
  - task
  - mcp
- name: SCIM 2.0 Provisioning
  tags:
  - scim