Calls without X-API-Key need no key. Calls with it need a paid plan — get a key.
Get an API key
Free tier, no form to fill in. Signing in shares your email address with us — we
store it to create your key and to recognise you if you sign in with another
provider. See our Privacy Policy and
Terms.
openapi: 3.2.0
info:
title: Comms Webhooks API
version: 1.0.0
description: 'Send and receive texts, place and answer calls, and create payment requests from your Comms workspace. Base URL: `https://osis.co/api/v1/comms`. The Payments API has to be turned on for your workspace first.'
servers:
- url: https://osis.co/api/v1/comms
description: Production
- url: https://comms.osis.co/api/v1/comms
description: Comms host alias
security:
- bearerAuth: []
tags:
- name: Webhooks
paths:
/webhooks:
get:
operationId: listWebhooks
summary: List webhooks
description: 'List your webhooks. Scope: `comms_webhooks`.'
responses:
'200':
description: Webhook list
content:
application/json:
schema:
type: object
properties:
webhooks:
type: array
items:
$ref: '#/components/schemas/Webhook'
'401':
$ref: '#/components/responses/Unauthorized'
'403':
$ref: '#/components/responses/Forbidden'
tags:
- Webhooks
post:
operationId: createWebhook
summary: Create a webhook
description: 'Add an HTTPS URL where Comms will send events. Scope: `comms_webhooks`.'
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/CreateWebhookRequest'
responses:
'201':
description: Webhook created
content:
application/json:
schema:
type: object
properties:
webhook:
$ref: '#/components/schemas/Webhook'
'401':
$ref: '#/components/responses/Unauthorized'
'403':
$ref: '#/components/responses/Forbidden'
tags:
- Webhooks
components:
schemas:
CreateWebhookRequest:
type: object
required:
- url
properties:
url:
type: string
format: uri
events:
type: array
items:
type: string
description: The events you want, like comms.message.received, comms.message.edited, comms.message.sent, or comms.message.read. For one-to-one iMessage and RCS, comms.message.read fires when the recipient's phone sends a read receipt (read receipts must be on); never for SMS. No receipt does not mean unread. Leave it out to get every event that exists when you create the webhook.
Webhook:
type: object
properties:
id:
type: string
url:
type: string
format: uri
events:
type: array
items:
type: string
active:
type: boolean
secret:
type: string
createdAt:
type: string
format: date-time
Error:
type: object
properties:
error:
type: string
code:
type: string
retry_after:
type: integer
reason:
type: string
responses:
Forbidden:
description: Your key doesn't have the scope this needs
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
Unauthorized:
description: API key is missing or wrong
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
securitySchemes:
bearerAuth:
type: http
scheme: bearer
bearerFormat: API key
description: Your API key from the Comms dashboard (`osis_…`).