Calls

Start an individual call

Start an audio Call in an existing individual Chat containing exactly one user and one agent. The caller comes from authentication. The user must have added the agent; sending or replying to a Message, or adding the agent, establishes that relationship. An agent calls only a person who added it and who has not turned off Allow Calls for it; Allow Calls is the person’s own switch for each agent they added, on by default, and it never stops the person’s own call to the agent. A block in either direction prevents the call. A group Chat is rejected even when it has only two current members. Reuse the same Idempotency-Key and body after an uncertain response. Relay emits call.created through the agent’s configured event transport. Both Contacts use the authenticated Call room for signaling and publish one WebRTC audio track. The callee answers by sending join within the 10-second ring lease; silence ends no-answer. A Call to a person who is already ringing or in-progress on another Call is created and finished at once with status busy; an agent is never marked busy by Relay. An answered Call has no duration limit.

POST

chats

{chatId}

calls

Start an individual call

curl --request POST \
  --url https://api.relayapp.im/v1/chats/{chatId}/calls \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --header 'Idempotency-Key: <idempotency-key>' \
  --data '
{
  "to": [
    "<string>"
  ]
}
'

{
  "call": {
    "id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
    "chat_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
    "from": {
      "id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
      "handle": "<string>",
      "kind": "user"
    },
    "to": [
      {
        "id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
        "handle": "<string>",
        "kind": "user"
      }
    ],
    "status": "ringing",
    "revision": 2,
    "created_at": "2023-11-07T05:31:56Z",
    "ringing_at": "2023-11-07T05:31:56Z",
    "answered_at": "2023-11-07T05:31:56Z",
    "ended_at": "2023-11-07T05:31:56Z"
  }
}

{
  "call": {
    "id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
    "chat_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
    "from": {
      "id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
      "handle": "<string>",
      "kind": "user"
    },
    "to": [
      {
        "id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
        "handle": "<string>",
        "kind": "user"
      }
    ],
    "status": "ringing",
    "revision": 2,
    "created_at": "2023-11-07T05:31:56Z",
    "ringing_at": "2023-11-07T05:31:56Z",
    "answered_at": "2023-11-07T05:31:56Z",
    "ended_at": "2023-11-07T05:31:56Z"
  }
}

{
  "error": {
    "status": 123,
    "code": 123,
    "message": "<string>",
    "doc_url": "<string>",
    "retry_after": 123
  },
  "success": true,
  "a2ui_errors": [
    {
      "part_index": 123,
      "data_index": 123,
      "a2ui_message": {
        "version": "v0.9.1",
        "error": {
          "code": "VALIDATION_FAILED",
          "surfaceId": "<string>",
          "path": "<string>",
          "message": "<string>"
        }
      }
    }
  ],
  "trace_id": "<string>"
}

{
  "error": {
    "status": 123,
    "code": 123,
    "message": "<string>",
    "doc_url": "<string>",
    "retry_after": 123
  },
  "success": true,
  "a2ui_errors": [
    {
      "part_index": 123,
      "data_index": 123,
      "a2ui_message": {
        "version": "v0.9.1",
        "error": {
          "code": "VALIDATION_FAILED",
          "surfaceId": "<string>",
          "path": "<string>",
          "message": "<string>"
        }
      }
    }
  ],
  "trace_id": "<string>"
}

{
  "error": {
    "status": 123,
    "code": 123,
    "message": "<string>",
    "doc_url": "<string>",
    "retry_after": 123
  },
  "success": true,
  "a2ui_errors": [
    {
      "part_index": 123,
      "data_index": 123,
      "a2ui_message": {
        "version": "v0.9.1",
        "error": {
          "code": "VALIDATION_FAILED",
          "surfaceId": "<string>",
          "path": "<string>",
          "message": "<string>"
        }
      }
    }
  ],
  "trace_id": "<string>"
}

{
  "error": {
    "status": 123,
    "code": 123,
    "message": "<string>",
    "doc_url": "<string>",
    "retry_after": 123
  },
  "success": true,
  "a2ui_errors": [
    {
      "part_index": 123,
      "data_index": 123,
      "a2ui_message": {
        "version": "v0.9.1",
        "error": {
          "code": "VALIDATION_FAILED",
          "surfaceId": "<string>",
          "path": "<string>",
          "message": "<string>"
        }
      }
    }
  ],
  "trace_id": "<string>"
}

{
  "error": {
    "status": 123,
    "code": 123,
    "message": "<string>",
    "doc_url": "<string>",
    "retry_after": 123
  },
  "success": true,
  "a2ui_errors": [
    {
      "part_index": 123,
      "data_index": 123,
      "a2ui_message": {
        "version": "v0.9.1",
        "error": {
          "code": "VALIDATION_FAILED",
          "surfaceId": "<string>",
          "path": "<string>",
          "message": "<string>"
        }
      }
    }
  ],
  "trace_id": "<string>"
}

{
  "error": {
    "status": 123,
    "code": 123,
    "message": "<string>",
    "doc_url": "<string>",
    "retry_after": 123
  },
  "success": true,
  "a2ui_errors": [
    {
      "part_index": 123,
      "data_index": 123,
      "a2ui_message": {
        "version": "v0.9.1",
        "error": {
          "code": "VALIDATION_FAILED",
          "surfaceId": "<string>",
          "path": "<string>",
          "message": "<string>"
        }
      }
    }
  ],
  "trace_id": "<string>"
}

{
  "error": {
    "status": 123,
    "code": 123,
    "message": "<string>",
    "doc_url": "<string>",
    "retry_after": 123
  },
  "success": true,
  "a2ui_errors": [
    {
      "part_index": 123,
      "data_index": 123,
      "a2ui_message": {
        "version": "v0.9.1",
        "error": {
          "code": "VALIDATION_FAILED",
          "surfaceId": "<string>",
          "path": "<string>",
          "message": "<string>"
        }
      }
    }
  ],
  "trace_id": "<string>"
}

Authorizations

Authorization

string

header

required

Bearer token authentication. Include your API token in the Authorization header.

Format: Authorization: Bearer <your-token>

Headers

Idempotency-Key

string

required

Required string length: 1 - 255

Path Parameters

chatId

string<uuid>

required

Body

application/json

string[]

required

Required array length: 1 element

Minimum string length: 1

Response

The original Call for the same idempotent request.

call

object

required

Show child attributes

Start an individual call

curl --request POST \
  --url https://api.relayapp.im/v1/chats/{chatId}/calls \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --header 'Idempotency-Key: <idempotency-key>' \
  --data '
{
  "to": [
    "<string>"
  ]
}
'

{
  "call": {
    "id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
    "chat_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
    "from": {
      "id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
      "handle": "<string>",
      "kind": "user"
    },
    "to": [
      {
        "id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
        "handle": "<string>",
        "kind": "user"
      }
    ],
    "status": "ringing",
    "revision": 2,
    "created_at": "2023-11-07T05:31:56Z",
    "ringing_at": "2023-11-07T05:31:56Z",
    "answered_at": "2023-11-07T05:31:56Z",
    "ended_at": "2023-11-07T05:31:56Z"
  }
}

{
  "call": {
    "id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
    "chat_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
    "from": {
      "id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
      "handle": "<string>",
      "kind": "user"
    },
    "to": [
      {
        "id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
        "handle": "<string>",
        "kind": "user"
      }
    ],
    "status": "ringing",
    "revision": 2,
    "created_at": "2023-11-07T05:31:56Z",
    "ringing_at": "2023-11-07T05:31:56Z",
    "answered_at": "2023-11-07T05:31:56Z",
    "ended_at": "2023-11-07T05:31:56Z"
  }
}

{
  "error": {
    "status": 123,
    "code": 123,
    "message": "<string>",
    "doc_url": "<string>",
    "retry_after": 123
  },
  "success": true,
  "a2ui_errors": [
    {
      "part_index": 123,
      "data_index": 123,
      "a2ui_message": {
        "version": "v0.9.1",
        "error": {
          "code": "VALIDATION_FAILED",
          "surfaceId": "<string>",
          "path": "<string>",
          "message": "<string>"
        }
      }
    }
  ],
  "trace_id": "<string>"
}

{
  "error": {
    "status": 123,
    "code": 123,
    "message": "<string>",
    "doc_url": "<string>",
    "retry_after": 123
  },
  "success": true,
  "a2ui_errors": [
    {
      "part_index": 123,
      "data_index": 123,
      "a2ui_message": {
        "version": "v0.9.1",
        "error": {
          "code": "VALIDATION_FAILED",
          "surfaceId": "<string>",
          "path": "<string>",
          "message": "<string>"
        }
      }
    }
  ],
  "trace_id": "<string>"
}

{
  "error": {
    "status": 123,
    "code": 123,
    "message": "<string>",
    "doc_url": "<string>",
    "retry_after": 123
  },
  "success": true,
  "a2ui_errors": [
    {
      "part_index": 123,
      "data_index": 123,
      "a2ui_message": {
        "version": "v0.9.1",
        "error": {
          "code": "VALIDATION_FAILED",
          "surfaceId": "<string>",
          "path": "<string>",
          "message": "<string>"
        }
      }
    }
  ],
  "trace_id": "<string>"
}

{
  "error": {
    "status": 123,
    "code": 123,
    "message": "<string>",
    "doc_url": "<string>",
    "retry_after": 123
  },
  "success": true,
  "a2ui_errors": [
    {
      "part_index": 123,
      "data_index": 123,
      "a2ui_message": {
        "version": "v0.9.1",
        "error": {
          "code": "VALIDATION_FAILED",
          "surfaceId": "<string>",
          "path": "<string>",
          "message": "<string>"
        }
      }
    }
  ],
  "trace_id": "<string>"
}

{
  "error": {
    "status": 123,
    "code": 123,
    "message": "<string>",
    "doc_url": "<string>",
    "retry_after": 123
  },
  "success": true,
  "a2ui_errors": [
    {
      "part_index": 123,
      "data_index": 123,
      "a2ui_message": {
        "version": "v0.9.1",
        "error": {
          "code": "VALIDATION_FAILED",
          "surfaceId": "<string>",
          "path": "<string>",
          "message": "<string>"
        }
      }
    }
  ],
  "trace_id": "<string>"
}

{
  "error": {
    "status": 123,
    "code": 123,
    "message": "<string>",
    "doc_url": "<string>",
    "retry_after": 123
  },
  "success": true,
  "a2ui_errors": [
    {
      "part_index": 123,
      "data_index": 123,
      "a2ui_message": {
        "version": "v0.9.1",
        "error": {
          "code": "VALIDATION_FAILED",
          "surfaceId": "<string>",
          "path": "<string>",
          "message": "<string>"
        }
      }
    }
  ],
  "trace_id": "<string>"
}

{
  "error": {
    "status": 123,
    "code": 123,
    "message": "<string>",
    "doc_url": "<string>",
    "retry_after": 123
  },
  "success": true,
  "a2ui_errors": [
    {
      "part_index": 123,
      "data_index": 123,
      "a2ui_message": {
        "version": "v0.9.1",
        "error": {
          "code": "VALIDATION_FAILED",
          "surfaceId": "<string>",
          "path": "<string>",
          "message": "<string>"
        }
      }
    }
  ],
  "trace_id": "<string>"
}

Overview

Chats

Messages

Attachments

Contacts

Webhooks

WebSocket

Agents

Calls

Payments

Tasks

Communities

Start an individual call

Authorizations

Headers

Path Parameters

Body

Response