> 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/calls.md).

# Calls

Read past calls, including transcripts and captured variables.

## GET /calls

> List calls

```json
{"openapi":"3.0.3","info":{"title":"HeyGuest External API","version":"1.1.0"},"tags":[{"name":"Calls","description":"Read past calls, including transcripts and captured variables."}],"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"}}}}},"CallSummary":{"type":"object","properties":{"id":{"type":"string","description":"Same as `room_name`."},"room_name":{"type":"string"},"caller_phone":{"type":"string","nullable":true},"destination_phone":{"type":"string","nullable":true},"start_time":{"type":"string","format":"date-time","nullable":true},"end_time":{"type":"string","format":"date-time","nullable":true},"duration_seconds":{"type":"integer","nullable":true},"ai_summary":{"type":"string","nullable":true},"variables_count":{"type":"integer"}}}}},"paths":{"/calls":{"get":{"tags":["Calls"],"summary":"List calls","operationId":"listCalls","parameters":[{"in":"query","name":"phone","schema":{"type":"string"},"description":"Filter calls to a specific caller. Leading `+` is accepted; both\nnormalized forms are searched.\n"},{"in":"query","name":"page","schema":{"type":"integer","minimum":1,"default":1}}],"responses":{"200":{"description":"Paginated list of calls (summary fields).","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/Pagination"},{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/CallSummary"}}}}]}}}}}}}}}
```

## Latest call from a caller

> Returns the most recent call from the given caller phone number, with\
> full transcript, AI summary, and captured variables.<br>

```json
{"openapi":"3.0.3","info":{"title":"HeyGuest External API","version":"1.1.0"},"tags":[{"name":"Calls","description":"Read past calls, including transcripts and captured variables."}],"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":{"CallDetail":{"allOf":[{"$ref":"#/components/schemas/CallSummary"},{"type":"object","properties":{"transcript":{"type":"string","nullable":true},"transferred_to_phone":{"type":"string","nullable":true},"transfer_reason":{"type":"string","nullable":true},"booking_initiated":{"type":"boolean","nullable":true},"booking_successful":{"type":"boolean","nullable":true},"variables":{"type":"array","items":{"type":"object","properties":{"name":{"type":"string"},"value":{"type":"string","nullable":true},"updated_at":{"type":"string","format":"date-time","nullable":true}}}}}}]},"CallSummary":{"type":"object","properties":{"id":{"type":"string","description":"Same as `room_name`."},"room_name":{"type":"string"},"caller_phone":{"type":"string","nullable":true},"destination_phone":{"type":"string","nullable":true},"start_time":{"type":"string","format":"date-time","nullable":true},"end_time":{"type":"string","format":"date-time","nullable":true},"duration_seconds":{"type":"integer","nullable":true},"ai_summary":{"type":"string","nullable":true},"variables_count":{"type":"integer"}}}}},"paths":{"/calls/{phone}/latest":{"get":{"tags":["Calls"],"summary":"Latest call from a caller","description":"Returns the most recent call from the given caller phone number, with\nfull transcript, AI summary, and captured variables.\n","operationId":"getLatestCall","parameters":[{"in":"path","name":"phone","required":true,"schema":{"type":"string","pattern":"^\\+?[0-9]+$"},"description":"Caller's phone number. Leading `+` is accepted."}],"responses":{"200":{"description":"Call detail.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/CallDetail"}}}}}},"404":{"description":"No call exists for this caller in your team."}}}}}}
```

## GET /calls/{room\_name}

> Read a call by room name

```json
{"openapi":"3.0.3","info":{"title":"HeyGuest External API","version":"1.1.0"},"tags":[{"name":"Calls","description":"Read past calls, including transcripts and captured variables."}],"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":{"CallDetail":{"allOf":[{"$ref":"#/components/schemas/CallSummary"},{"type":"object","properties":{"transcript":{"type":"string","nullable":true},"transferred_to_phone":{"type":"string","nullable":true},"transfer_reason":{"type":"string","nullable":true},"booking_initiated":{"type":"boolean","nullable":true},"booking_successful":{"type":"boolean","nullable":true},"variables":{"type":"array","items":{"type":"object","properties":{"name":{"type":"string"},"value":{"type":"string","nullable":true},"updated_at":{"type":"string","format":"date-time","nullable":true}}}}}}]},"CallSummary":{"type":"object","properties":{"id":{"type":"string","description":"Same as `room_name`."},"room_name":{"type":"string"},"caller_phone":{"type":"string","nullable":true},"destination_phone":{"type":"string","nullable":true},"start_time":{"type":"string","format":"date-time","nullable":true},"end_time":{"type":"string","format":"date-time","nullable":true},"duration_seconds":{"type":"integer","nullable":true},"ai_summary":{"type":"string","nullable":true},"variables_count":{"type":"integer"}}}}},"paths":{"/calls/{room_name}":{"get":{"tags":["Calls"],"summary":"Read a call by room name","operationId":"getCall","parameters":[{"in":"path","name":"room_name","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Call detail.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/CallDetail"}}}}}},"404":{"description":"Call not found in your team."}}}}}}
```