> For the complete documentation index, see [llms.txt](https://heyguest-ai.gitbook.io/heyguest/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://heyguest-ai.gitbook.io/heyguest/reference/channels.md). # Channels List channels and bind vox numbers to custom assistants. The carrier-side routing (pointing the number at HeyGuest's LiveKit ingress) must be done before calling `POST /channels` — the API only performs the LiveKit-side setup. ## GET /channels > List channels ```json {"openapi":"3.0.3","info":{"title":"HeyGuest External API","version":"1.1.0"},"tags":[{"name":"Channels","description":"List channels and bind vox numbers to custom assistants. The carrier-side\nrouting (pointing the number at HeyGuest's LiveKit ingress) must be done\nbefore calling `POST /channels` — the API only performs the LiveKit-side\nsetup.\n"}],"servers":[{"url":"https://app.heyguest.ai/api/v1","description":"Production"}],"security":[{"bearerAuth":[]}],"components":{"securitySchemes":{"bearerAuth":{"type":"http","scheme":"bearer","bearerFormat":"Sanctum personal access token (team-scoped)"}},"schemas":{"Pagination":{"type":"object","properties":{"links":{"type":"object","properties":{"first":{"type":"string","nullable":true},"last":{"type":"string","nullable":true},"prev":{"type":"string","nullable":true},"next":{"type":"string","nullable":true}}},"meta":{"type":"object","properties":{"current_page":{"type":"integer"},"from":{"type":"integer","nullable":true},"last_page":{"type":"integer"},"path":{"type":"string"},"per_page":{"type":"integer"},"to":{"type":"integer","nullable":true},"total":{"type":"integer"}}}}},"Channel":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"uuid":{"type":"string","format":"uuid","description":"Same value as `id`."},"type":{"type":"string","enum":["voice","whatsapp","facebook","instagram","webchat"]},"name":{"type":"string"},"location_id":{"type":"string","format":"uuid","nullable":true},"whatsapp":{"nullable":true,"type":"object","description":"Only present when `type` is `whatsapp`.","properties":{"business_id":{"type":"string"},"phone_number_id":{"type":"string"}}},"vox_number":{"type":"string","nullable":true,"description":"Normalized vox number (no leading `+`). Only present when `type` is\n`voice`.\n"},"assistant_uuid":{"type":"string","format":"uuid","nullable":true,"description":"UUID of the bound assistant. Only present when `type` is `voice`.\n"},"status":{"type":"string","nullable":true,"description":"High-level channel status (e.g. `active`). Only present when `type`\nis `voice`.\n"},"created_at":{"type":"string","format":"date-time"},"updated_at":{"type":"string","format":"date-time"}}}}},"paths":{"/channels":{"get":{"tags":["Channels"],"summary":"List channels","operationId":"listChannels","parameters":[{"in":"query","name":"type","schema":{"type":"string","enum":["voice","whatsapp","facebook","instagram","webchat"]},"description":"Filter to a single channel type."},{"in":"query","name":"page","schema":{"type":"integer","minimum":1,"default":1}}],"responses":{"200":{"description":"Paginated list of channels.","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/Pagination"},{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/Channel"}}}}]}}}}}}}}} ``` ## Bind a vox number to a custom assistant > Provisions a new voice channel, or rebinds an existing one to a different\ > custom assistant.\ > \ > \- \*\*Idempotent.\*\* If the vox number is already bound in your team, the\ > call rebinds it (the underlying LiveKit trunk is left in place).\ > \- \*\*Atomic.\*\* If LiveKit setup fails, no Channel row is written — your\ > retry produces a clean attempt.\ > \- The carrier-side routing (pointing the number at HeyGuest's LiveKit\ > ingress) must be done \*\*before\*\* calling this endpoint.
```json {"openapi":"3.0.3","info":{"title":"HeyGuest External API","version":"1.1.0"},"tags":[{"name":"Channels","description":"List channels and bind vox numbers to custom assistants. The carrier-side\nrouting (pointing the number at HeyGuest's LiveKit ingress) must be done\nbefore calling `POST /channels` — the API only performs the LiveKit-side\nsetup.\n"}],"servers":[{"url":"https://app.heyguest.ai/api/v1","description":"Production"}],"security":[{"bearerAuth":[]}],"components":{"securitySchemes":{"bearerAuth":{"type":"http","scheme":"bearer","bearerFormat":"Sanctum personal access token (team-scoped)"}},"schemas":{"ChannelWritable":{"type":"object","required":["name","vox_number","assistant_uuid"],"description":"Body for `POST /channels`.","properties":{"name":{"type":"string","maxLength":255,"description":"Display name for this channel."},"vox_number":{"type":"string","pattern":"^\\+?[\\s0-9]+$","description":"E.164-style international number. Leading `+` and whitespace are\naccepted and stripped server-side. After normalization must match\n`^[1-9][0-9]{6,14}$`.\n"},"assistant_uuid":{"type":"string","format":"uuid","description":"UUID of a **custom** assistant in your team. Validation fails with\n`422` if the UUID does not resolve to a custom assistant you own.\n"}}},"Channel":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"uuid":{"type":"string","format":"uuid","description":"Same value as `id`."},"type":{"type":"string","enum":["voice","whatsapp","facebook","instagram","webchat"]},"name":{"type":"string"},"location_id":{"type":"string","format":"uuid","nullable":true},"whatsapp":{"nullable":true,"type":"object","description":"Only present when `type` is `whatsapp`.","properties":{"business_id":{"type":"string"},"phone_number_id":{"type":"string"}}},"vox_number":{"type":"string","nullable":true,"description":"Normalized vox number (no leading `+`). Only present when `type` is\n`voice`.\n"},"assistant_uuid":{"type":"string","format":"uuid","nullable":true,"description":"UUID of the bound assistant. Only present when `type` is `voice`.\n"},"status":{"type":"string","nullable":true,"description":"High-level channel status (e.g. `active`). Only present when `type`\nis `voice`.\n"},"created_at":{"type":"string","format":"date-time"},"updated_at":{"type":"string","format":"date-time"}}},"ValidationError":{"type":"object","properties":{"errors":{"type":"object","description":"Map of field name → array of error messages.","additionalProperties":{"type":"array","items":{"type":"string"}}}}},"LiveKitSetupError":{"type":"object","description":"Returned with `502` when LiveKit upstream setup fails on `POST /channels`.\nThe Channel row is not persisted — retry the request to attempt again.\n","properties":{"message":{"type":"string"},"error_code":{"type":"string","enum":["livekit_setup_failed"]}}}}},"paths":{"/channels":{"post":{"tags":["Channels"],"summary":"Bind a vox number to a custom assistant","description":"Provisions a new voice channel, or rebinds an existing one to a different\ncustom assistant.\n\n- **Idempotent.** If the vox number is already bound in your team, the\n call rebinds it (the underlying LiveKit trunk is left in place).\n- **Atomic.** If LiveKit setup fails, no Channel row is written — your\n retry produces a clean attempt.\n- The carrier-side routing (pointing the number at HeyGuest's LiveKit\n ingress) must be done **before** calling this endpoint.\n","operationId":"storeChannel","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ChannelWritable"}}}},"responses":{"200":{"description":"Existing channel rebound to a different assistant.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/Channel"}}}}}},"201":{"description":"New channel provisioned.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/Channel"}}}}}},"404":{"description":"The vox number is already bound in another HeyGuest team."},"422":{"description":"Validation failed — malformed `vox_number`, missing fields, or\n`assistant_uuid` does not resolve to a custom assistant in your team.\n","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ValidationError"}}}},"502":{"description":"LiveKit upstream failure. Safe to retry.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/LiveKitSetupError"}}}}}}}}} ``` ## GET /channels/{vox\_number} > Read a voice channel by vox number ```json {"openapi":"3.0.3","info":{"title":"HeyGuest External API","version":"1.1.0"},"tags":[{"name":"Channels","description":"List channels and bind vox numbers to custom assistants. The carrier-side\nrouting (pointing the number at HeyGuest's LiveKit ingress) must be done\nbefore calling `POST /channels` — the API only performs the LiveKit-side\nsetup.\n"}],"servers":[{"url":"https://app.heyguest.ai/api/v1","description":"Production"}],"security":[{"bearerAuth":[]}],"components":{"securitySchemes":{"bearerAuth":{"type":"http","scheme":"bearer","bearerFormat":"Sanctum personal access token (team-scoped)"}},"schemas":{"Channel":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"uuid":{"type":"string","format":"uuid","description":"Same value as `id`."},"type":{"type":"string","enum":["voice","whatsapp","facebook","instagram","webchat"]},"name":{"type":"string"},"location_id":{"type":"string","format":"uuid","nullable":true},"whatsapp":{"nullable":true,"type":"object","description":"Only present when `type` is `whatsapp`.","properties":{"business_id":{"type":"string"},"phone_number_id":{"type":"string"}}},"vox_number":{"type":"string","nullable":true,"description":"Normalized vox number (no leading `+`). Only present when `type` is\n`voice`.\n"},"assistant_uuid":{"type":"string","format":"uuid","nullable":true,"description":"UUID of the bound assistant. Only present when `type` is `voice`.\n"},"status":{"type":"string","nullable":true,"description":"High-level channel status (e.g. `active`). Only present when `type`\nis `voice`.\n"},"created_at":{"type":"string","format":"date-time"},"updated_at":{"type":"string","format":"date-time"}}}}},"paths":{"/channels/{vox_number}":{"get":{"tags":["Channels"],"summary":"Read a voice channel by vox number","operationId":"getChannel","responses":{"200":{"description":"Channel.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/Channel"}}}}}},"404":{"description":"No voice channel matches this vox number in your team."}}}}}} ```