Signal Messages API

openapi: 3.2.0
info:
  title: Signal Server Messages API
  description: The Signal Server API is the backend REST API that supports the Signal Private Messenger applications on Android, Desktop, and iOS.
  version: '2.0'
  contact:
    name: Signal Support
    url: https://support.signal.org/
  termsOfService: https://signal.org/legal/
  license:
    name: AGPL-3.0
    url: https://github.com/signalapp/Signal-Server/blob/main/LICENSE
servers:
- url: https://chat.signal.org
  description: Signal Production Server
security:
- basicAuth: []
tags:
- name: Messages
  description: Message sending and receiving endpoints for delivering encrypted messages between Signal users.
paths:
  /v1/messages/{destinationUuid}:
    put:
      operationId: sendMessage
      summary: Send an encrypted message
      description: Sends one or more encrypted messages to the specified destination account identified by UUID. Messages are encrypted using the Signal Protocol and include envelope metadata for delivery. The server routes messages to the recipient's devices.
      tags:
      - Messages
      parameters:
      - $ref: '#/components/parameters/destinationUuid'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/IncomingMessageList'
      responses:
        '200':
          description: Messages accepted for delivery
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SendMessageResponse'
        '401':
          description: Authentication required
        '404':
          description: Destination account not found
        '409':
          description: Mismatched devices
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/MismatchedDevices'
        '410':
          description: Stale devices
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/StaleDevices'
components:
  parameters:
    destinationUuid:
      name: destinationUuid
      in: path
      required: true
      description: The UUID of the destination account.
      schema:
        type: string
        format: uuid
  schemas:
    StaleDevices:
      type: object
      properties:
        staleDevices:
          type: array
          description: Device IDs with stale registration IDs.
          items:
            type: integer
            format: int64
    SendMessageResponse:
      type: object
      properties:
        needsSync:
          type: boolean
          description: Whether the sender has other devices that need to be synced with this message.
    IncomingMessageList:
      type: object
      required:
      - messages
      - timestamp
      properties:
        messages:
          type: array
          description: The list of encrypted message envelopes, one per destination device.
          items:
            $ref: '#/components/schemas/IncomingMessage'
        timestamp:
          type: integer
          format: int64
          description: The client timestamp in milliseconds.
        online:
          type: boolean
          description: Whether to only deliver to online devices (skip push notifications for offline devices).
        urgent:
          type: boolean
          description: Whether the message is urgent and should trigger immediate push notification delivery.
    IncomingMessage:
      type: object
      required:
      - type
      - destinationDeviceId
      - content
      properties:
        type:
          type: integer
          description: The message envelope type. 1 for ciphertext, 3 for prekey message, 6 for plaintext content, 7 for unidentified sender.
          enum:
          - 1
          - 3
          - 6
          - 7
        destinationDeviceId:
          type: integer
          format: int64
          description: The target device identifier on the destination account.
        destinationRegistrationId:
          type: integer
          description: The expected registration ID of the target device.
        content:
          type: string
          description: The Base64-encoded encrypted message content.
    MismatchedDevices:
      type: object
      properties:
        missingDevices:
          type: array
          description: Device IDs that messages were not provided for.
          items:
            type: integer
            format: int64
        extraDevices:
          type: array
          description: Device IDs that messages were provided for but do not exist.
          items:
            type: integer
            format: int64
  securitySchemes:
    basicAuth:
      type: http
      scheme: basic
      description: HTTP Basic authentication using the account UUID (or phone number) and password. The password is established during account registration.
    bearerAuth:
      type: http
      scheme: bearer
      description: Bearer token authentication used for certain provisioning and registration flows.
externalDocs:
  description: Signal Server Source Code
  url: https://github.com/signalapp/Signal-Server