Interactions - Wavelength

API Key

You must first create an API Key in Wavelength. It is located under “Manage Integrations”, then scroll to the bottom and click “Manage API Keys”. Here, you can see your existing keys, their names and expiration. You can delete existing ones. When creating a new API key, the name must be unique in your organization. Once the key has been created, you will be shown a one-time dialog box with your new API key. You should copy this down somewhere safe — we will not show this again. If you lose your API key, you will need to make a new one. For these endpoints, set the Authorization header to your API key value directly (for example Authorization: <API_KEY>). Do not add a Bearer prefix; the full header value is validated as the key.

Sending Events

Here is the API endpoint for sending events to Wavelength. The only required field is query:

curl -X \
 POST https://api.wavelength.cx/interactions \
 -F "query=Sample query text" \
 -H "Authorization: <API_KEY>" \
 -H "Content-Type: multipart/form-data" 

If you want to specify who is sending/creating the ticket, include a user. The user must have at least one of these fields: email, source_specific_id, or id (the Wavelength ID). We will match the user to an existing Wavelength customer/contact based on these fields. If no matching Wavelength user exists, the user will be created. Other optional fields include name, username, image_url. If you want to match the interaction to a specific company account, please include the company_source_specific_id or the company_id (the company’s Wavelength ID). You can also pass in other optional fields like the title, original timestamp, and additional attributes.

Source Specific ID

You can include a source_specific_id to give the ticket a unique identifier. This is useful for:

Deduplication: Prevent duplicate tickets from being created
Replying: Use this ID later to add replies to the ticket via the /interactions/reply endpoint

curl -X \
 POST https://api.wavelength.cx/interactions \
 -F "title=Sample title" \
 -F "query=Sample query text" \
 -F "source_specific_id=my_ticket_123" \
 -F "user={\"email\": \"user@example.com\", \"name\": \"John Doe\"}" \
 -F "original_timestamp=2024-06-10T18:34:00Z" \
 -H "Authorization: <API_KEY>" \
 -H "Content-Type: multipart/form-data"

You can then reply to this ticket using the source_specific_id:

curl -X POST "https://api.wavelength.cx/interactions/reply?source_specific_id=my_ticket_123" \
  -H "Authorization: <API_KEY>" \
  -F "content=This is a reply to the ticket" \
  -F 'user={"email":"agent@example.com","name":"Support Agent"}'

Full Example with All Fields

curl -X \
 POST https://api.wavelength.cx/interactions \
 -F "title=Sample title" \
 -F "query=Sample query text" \
 -F "source_specific_id=unique_ticket_id" \
 -F "user={\"email\": \"user@example.com\", \"name\": \"John Doe\", \"source_specific_id\": \"userSSID\"}" \
 -F "company_source_specific_id=companySSID" \
 -F "additional_properties={\"key1\": \"value1\", \"key2\": 123, \"key3\": \"value3\"}" \
 -F "original_timestamp=2024-06-10T18:34:00Z" \
 -H "Authorization: <API_KEY>" \
 -H "Content-Type: multipart/form-data"

curl -X \
 POST https://api.wavelength.cx/interactions \
 -F "title=Sample title" \
 -F "query=Sample query text" \
 -F "user={\"email\": \"user@example.com\", \"name\": \"John Doe\"}" \
 -F "company_id=01945162-52fc-739b-98de-e2ac9f2eec49" \
 -F "additional_properties={\"key1\": \"value1\", \"key2\": 123, \"key3\": \"value3\"}" \
 -F "original_timestamp=2024-06-10T18:34:00Z" \
 -H "Authorization: <API_KEY>" \
 -H "Content-Type: multipart/form-data"

You can also pass in a base64 encoded image if you prefer, or an image URL:

curl -X POST https://api.wavelength.cx/interactions \
-F "query=Sample query text" \
-F "files_base64=<base64 encoded image>" \
-H "Authorization: <API_KEY>" \
-H "Content-Type: multipart/form-data"

curl -X POST https://api.wavelength.cx/interactions \
-F "query=Sample query text" \
-F "files_image_url=https://example.com/img.jpg" \
-H "Authorization: <API_KEY>" \
-H "Content-Type: multipart/form-data"

You can attach multiple images by passing in multiple files.

curl -X POST https://api.wavelength.cx/interactions \
-F "query=Sample query text" \
-F "files_base64=<base64 encoded image_1>" \
-F "files_base64=<base64 encoded image_2>" \
-H "Authorization: <API_KEY>" \
-H "Content-Type: multipart/form-data"

The files field is used to send images to Wavelength. You can currently send JPG and PNG images up to 4MB in size. Here are some of the errors that may be returned:

400: Invalid request - missing title, file too large, couldn’t be opened, etc.
401: Invalid API Key or expired API Key
503: Wavelength server error has been logged and our team has been notified

Errors take on the following format in JSON:

{"error": "message"}

Successful responses take on the following format in JSON:

{"created_ticket_number": "ASM-111"}

Rate Limiting

There is a rate limit of 30 events per second. If you exceed this, you will receive a 429 response code. If you need a higher rate, please let us know.

List Interactions

GET /interactions

Returns a paginated list of interactions (top-level tickets) for your organization.

Query Parameters

Parameter	Type	Required	Default	Description
`limit`	integer	No	50	Number of interactions to return. Must be between 1 and 200.
`offset`	integer	No	0	Number of interactions to skip (for pagination).
`status`	string	No	—	Filter by ticket status. Repeatable for multiple values. Valid values: `Open`, `NeedsResponse`, `Breaching`, `Escalated`, `Closed`. Case-sensitive.
`assignee_id`	string	No	—	Filter by assignee user ID. Repeatable for multiple values.
`company_id`	string	No	—	Filter by company ID. Repeatable for multiple values.
`customer_id`	string	No	—	Filter by customer/contact ID. Repeatable for multiple values.
`source`	string	No	—	Filter by source channel. Repeatable for multiple values. Valid values: `Slack`, `Gmail`, `Web`, `API`, `Zendesk`, `Intercom`, `Discord`, `GitHubTicket`.
`category_id`	string (UUID)	No	—	Filter by category ID. Repeatable for multiple values. Use `GET /categories` to list available IDs.
`tag_id`	string (UUID)	No	—	Filter by tag ID. Repeatable for multiple values. Use `GET /tags` to list available IDs.
`team_owner_id`	string (UUID)	No	—	Filter by the owning team’s ID. Use `GET /teams` to list available IDs.
`updated_after`	string	No	—	Return only interactions updated at or after this time. Accepts RFC3339 (`2026-06-01T00:00:00Z`) or bare date (`2026-06-01`).
`updated_before`	string	No	—	Return only interactions updated before this time. Same format as `updated_after`.

Example: List all interactions

curl -X GET "https://api.wavelength.cx/interactions?limit=50&offset=0" \
  -H "Authorization: <API_KEY>"

Example: Filter by status

curl -X GET "https://api.wavelength.cx/interactions?status=Open&limit=50" \
  -H "Authorization: <API_KEY>"

Example: Filter by multiple statuses

curl -X GET "https://api.wavelength.cx/interactions?status=Open&status=NeedsResponse&limit=50" \
  -H "Authorization: <API_KEY>"

Example: Filter by source

curl -X GET "https://api.wavelength.cx/interactions?source=Slack&limit=50" \
  -H "Authorization: <API_KEY>"

Example: Filter by source (multiple)

curl -X GET "https://api.wavelength.cx/interactions?source=Slack&source=Gmail&limit=50" \
  -H "Authorization: <API_KEY>"

Example: Filter by category

curl -X GET "https://api.wavelength.cx/interactions?category_id=<CATEGORY_UUID>&limit=50" \
  -H "Authorization: <API_KEY>"

Example: Filter by tag

curl -X GET "https://api.wavelength.cx/interactions?tag_id=<TAG_UUID>&limit=50" \
  -H "Authorization: <API_KEY>"

Example: Filter by team owner

curl -X GET "https://api.wavelength.cx/interactions?team_owner_id=<TEAM_UUID>&limit=50" \
  -H "Authorization: <API_KEY>"

Example: Incremental sync (interactions updated in the last 24 hours)

curl -X GET "https://api.wavelength.cx/interactions?updated_after=2026-07-16T00:00:00Z&limit=200" \
  -H "Authorization: <API_KEY>"

Response

{
  "data": [
    {
      "id": "01KXNWCA9Y6E2QRB9FSHDQZKGS",
      "ticket_identifier": "ASM",
      "ticket_number": 6579,
      "title": "Support request title",
      "query": "The original message content",
      "ticket_status": "Open",
      "source": "API",
      "url": "https://mail.google.com/...",
      "wavelength_url": "http://dashboard.askassembly.app/issue/ASM-6579",
      "created_at": "2026-07-16T16:32:57Z",
      "updated_at": "2026-07-16T16:37:59Z",
      "assignee_user_id": "user-uuid",
      "company_id": "company-uuid",
      "customer_id": "customer-uuid",
      "owner_replies": 1,
      "customer_replies": 2,
      "attributes": { "my_custom_attr": "value" },
      "user_info": { "id": "user@example.com", "name": "Jane Doe", "email": "user@example.com" },
      "company_info": { "id": "company-uuid", "name": "Acme Corp" }
    }
  ],
  "has_next_page": true,
  "next_cursor": 50
}

Field	Description
`url`	Source URL (Slack thread link, Gmail email link, etc.)
`wavelength_url`	Direct link to the ticket in the Wavelength dashboard
`attributes`	Custom account attributes cached on the interaction

To fetch the next page, pass `next_cursor` as the `offset` in your next request:

```bash
curl -X GET "https://api.wavelength.cx/interactions?limit=50&offset=50" \
  -H "Authorization: <API_KEY>"

Error Responses

Code	Meaning
400	Invalid `limit` (must be 1–200), invalid `offset` (must be ≥ 0), or missing auth
429	Rate limit exceeded

Get Interaction with History

GET /interactions/:id

Returns a single interaction and its full reply/message thread.

Path Parameters

Parameter	Type	Description
`id`	string	Wavelength ULID of the interaction

Example

curl -X GET "https://api.wavelength.cx/interactions/01KXNWCA9Y6E2QRB9FSHDQZKGS" \
  -H "Authorization: <API_KEY>"

Response

{
  "interaction": {
    "id": "01KXNWCA9Y6E2QRB9FSHDQZKGS",
    "ticket_identifier": "ASM",
    "ticket_number": 6579,
    "title": "Support request title",
    "query": "The original message content",
    "ticket_status": "Open",
    "source": "API",
    "url": "https://mail.google.com/...",
    "wavelength_url": "http://dashboard.askassembly.app/issue/ASM-6579",
    "created_at": "2026-07-16T16:32:57Z",
    "updated_at": "2026-07-16T16:37:59Z",
    "owner_replies": 1,
    "customer_replies": 2,
    "attributes": { "my_custom_attr": "value" },
    "company_info": { "id": "company-uuid", "name": "Acme Corp" },
    "user_info": { "id": "user@example.com", "name": "Jane Doe", "email": "user@example.com" }
  },
  "history": [
    {
      "id": "01KXNWCA9Y6E2QRB9FSHDQZKGT",
      "parent_id": "01KXNWCA9Y6E2QRB9FSHDQZKGS",
      "type": "Message",
      "content": "The original message content",
      "source": "Gmail",
      "created_at": "2026-07-16T16:32:57Z",
      "from": "customer@example.com",
      "to": ["support@company.com"],
      "cc": ["manager@company.com"]
    },
    {
      "id": "01KXNWCA9Y6E2QRB9FSHDQZKGU",
      "parent_id": "01KXNWCA9Y6E2QRB9FSHDQZKGS",
      "type": "Message",
      "content": "Thanks for reaching out! Looking into this now.",
      "source": "Web",
      "created_at": "2026-07-16T16:35:00Z",
      "from": "agent@company.com"
    }
  ]
}

The history array contains all messages, replies, and internal notes for the interaction in chronological order. The from field identifies the message author. For Gmail interactions, to and cc are included when available.

Error Responses

Code	Meaning
400	Missing or invalid auth
404	Interaction not found (wrong ID or belongs to a different org)
429	Rate limit exceeded

List Teams

GET /teams

Returns all teams in your organization. Use team IDs with the team_owner_id filter on GET /interactions.

Example

curl -X GET "https://api.wavelength.cx/teams" \
  -H "Authorization: <API_KEY>"

Response

{
  "data": [
    {
      "id": "fc12e902-f8ee-4176-947b-7f716469d1d6",
      "name": "Support",
      "description": "Customer support team"
    }
  ]
}

Error Responses

Code	Meaning
400	Missing or invalid auth
429	Rate limit exceeded

GET /categories

Returns all categories in your organization. Use category IDs with the category_id filter on GET /interactions.

Example

curl -X GET "https://api.wavelength.cx/categories" \
  -H "Authorization: <API_KEY>"

Response

{
  "data": [
    {
      "id": "0199868a-ec2d-7d36-bd94-749a4db30dfe",
      "name": "Bug Report"
    }
  ]
}

Error Responses

Code	Meaning
400	Missing or invalid auth
429	Rate limit exceeded

GET /tags

Returns all account tags in your organization. Use tag IDs with the tag_id filter on GET /interactions.

Example

curl -X GET "https://api.wavelength.cx/tags" \
  -H "Authorization: <API_KEY>"

Response

{
  "data": [
    {
      "id": "0195af0e-3213-78fc-a3cf-cb8c192abeaf",
      "name": "VIP",
      "description": "High-priority customer",
      "color": "#7695ff"
    }
  ]
}

Error Responses

Code	Meaning
400	Missing or invalid auth
429	Rate limit exceeded

Create Interaction Reply

POST /interactions/reply

Creates a new reply/message for an existing ticket. Supports multiple ticket identification methods and file attachments.

Query Parameters

Exactly one of the following is required:

Parameter	Type	Description
`id`	string	Wavelength ULID of the ticket to reply to
`source_specific_id`	string	Source-specific ID of the ticket to reply to

Headers

Content-Type: multipart/form-data (required for file uploads)
Authorization: <API_KEY> (required; raw key, no Bearer prefix)

Request Body (multipart/form-data)

Field	Type	Required	Description
`content`	string	Yes	The reply message content
`source_specific_id`	string	No	Unique identifier for this reply (for deduplication)
`original_timestamp`	string	No	Original timestamp in RFC3339 format
`user`	object	Yes	User information object
`files`	file[]	No	File attachments (multipart)
`files_image_url`	string	No	Comma-separated URLs of images to attach

User Object

Field	Type	Required	Description
`id`	string	No*	User ID
`name`	string	No	User name
`email`	string	No*	User email
`source_specific_id`	string	No	User’s source-specific ID

*At least one of id or email is required. If only email is provided, it will be used as the user identifier.

Ticket Identification

The endpoint requires exactly one query parameter for ticket identification:

id - Wavelength ULID of the ticket
source_specific_id - Source-specific ID of the ticket

Both parameters cannot be provided simultaneously, and at least one is required.

Example Request (with Wavelength ULID)

curl -X POST "https://api.wavelength.cx/interactions/reply?id=01KKXRZM9PJRKJ488ZK3PB6JPX" \
  -H "Authorization: <API_KEY>" \
  -F "content=This is my reply to the ticket" \
  -F 'user={"name":"John Doe","email":"john@example.com"}' \
  -F "source_specific_id=reply_12345"

Example Request (with source_specific_id)

curl -X POST "https://api.wavelength.cx/interactions/reply?source_specific_id=ticket_ss_123" \
  -H "Authorization: <API_KEY>" \
  -F "content=Reply via source specific ID" \
  -F "files=@attachment.pdf" \
  -F 'user={"name":"Jane Doe","email":"jane@example.com"}'

Example Request (with file uploads)

curl -X POST "https://api.wavelength.cx/interactions/reply?source_specific_id=ticket_abc123" \
  -H "Authorization: <API_KEY>" \
  -F "content=Here are the files you requested" \
  -F "files=@document1.pdf" \
  -F "files=@image.png" \
  -F "files_image_url=https://example.com/image1.jpg,https://example.com/image2.jpg" \
  -F 'user={"name":"Alice","email":"alice@example.com"}'

Response

{
  "created_history_id": "01H8X9Z7Y2W3R4T5U6V7W8X9Y"
}

Field	Type	Description
`created_history_id`	string	ULID of the created history record

Error Responses

400 Bad Request

{
  "error": "content is required"
}

{
  "error": "user is required"
}

{
  "error": "user.id or user.email is required"
}

{
  "error": "exactly one of id or source_specific_id must be provided"
}

{
  "error": "invalid ULID format for id parameter"
}

404 Not Found

{
  "error": "ticket not found for identifier: ticket_abc123"
}

409 Conflict (Duplicate)

{
  "error": "source specific id already exists"
}

413 Payload Too Large

{
  "error": "File size exceeds 32MB"
}

Important Notes

File Size Limit: 32MB per file
Supported File Types: Any file type can be uploaded
Deduplication: Duplicate source_specific_id values are rejected for Slack/Community Slack sources
User Requirement: User object with user.id is now mandatory (no anonymous users)
Query Parameter Exclusivity: Exactly one of id or source_specific_id must be provided, not both
Rate Limiting: Subject to rate limiting (60 requests per minute per API key/IP)

​API Key

​Sending Events

​Source Specific ID

​Full Example with All Fields

​Rate Limiting

​List Interactions

​GET /interactions

​Query Parameters

​Example: List all interactions

​Example: Filter by status

​Example: Filter by multiple statuses

​Example: Filter by source

​Example: Filter by source (multiple)

​Example: Filter by category

​Example: Filter by tag

​Example: Filter by team owner

​Example: Incremental sync (interactions updated in the last 24 hours)

​Response

​Error Responses

​Get Interaction with History

​GET /interactions/:id

​Path Parameters

​Example

​Response

​Error Responses

​List Teams

​GET /teams

​Example

​Response

​Error Responses

​List Categories

​GET /categories

​Example

​Response

​Error Responses

​List Tags

​GET /tags

​Example

​Response

​Error Responses

​Create Interaction Reply

​POST /interactions/reply

​Query Parameters

​Headers

​Request Body (multipart/form-data)

​User Object

​Ticket Identification

​Example Request (with Wavelength ULID)

​Example Request (with source_specific_id)

​Example Request (with file uploads)

​Response

​Error Responses

​400 Bad Request

​404 Not Found

​409 Conflict (Duplicate)

​413 Payload Too Large

​Important Notes

API Key

Sending Events

Source Specific ID

Full Example with All Fields

Rate Limiting

List Interactions

GET /interactions

Query Parameters

Example: List all interactions

Example: Filter by status

Example: Filter by multiple statuses

Example: Filter by source

Example: Filter by source (multiple)

Example: Filter by category

Example: Filter by tag

Example: Filter by team owner

Example: Incremental sync (interactions updated in the last 24 hours)

Response

Error Responses

Get Interaction with History

GET /interactions/:id

Path Parameters

Example

Response

Error Responses

List Teams

GET /teams

Example

Response

Error Responses

List Categories

GET /categories

Example

Response

Error Responses

List Tags

GET /tags

Example

Response

Error Responses

Create Interaction Reply

POST /interactions/reply

Query Parameters

Headers

Request Body (multipart/form-data)

User Object

Ticket Identification

Example Request (with Wavelength ULID)

Example Request (with source_specific_id)

Example Request (with file uploads)

Response

Error Responses

400 Bad Request

404 Not Found

409 Conflict (Duplicate)

413 Payload Too Large

Important Notes