# Chat Sessions

## Get Recent Chat Sessions

> Retrieve chat sessions from the past X hours across all contacts belonging to the authenticated user.\
> Supports optional filtering by session status and message inclusion.<br>

```json
{"openapi":"3.1.0","info":{"title":"DM Champ API","version":"1.0.0"},"servers":[{"url":"https://api.dmchamp.com/v1","description":"Production API Server"}],"security":[{"ApiKeyAuth":[]},{"UserIdAuth":[]}],"components":{"securitySchemes":{"ApiKeyAuth":{"type":"apiKey","in":"query","name":"apiKey","description":"Your DM Champ API key. Obtain from Settings → API Keys."},"UserIdAuth":{"type":"apiKey","in":"query","name":"userId","description":"Your DM Champ User ID. Alternative to apiKey authentication. Cannot be used for agency-only endpoints."}},"parameters":{"ApiKeyParam":{"name":"apiKey","in":"query","description":"API key for authentication. At least one of apiKey or userId is required for protected endpoints.","required":false,"schema":{"type":"string"}},"UserIdParam":{"name":"userId","in":"query","description":"User ID for authentication. Alternative to apiKey. At least one of apiKey or userId is required for protected endpoints.","required":false,"schema":{"type":"string"}}},"schemas":{"RecentChatSession":{"type":"object","description":"A recent chat session with contact details","properties":{"session_id":{"type":"string","description":"Unique session identifier"},"contact_id":{"type":"string","description":"Contact identifier"},"contact_name":{"type":"string","description":"Contact full name"},"contact_phone":{"type":"string","description":"Contact phone number"},"contact_email":{"type":"string","description":"Contact email address"},"start_date_time":{"type":"string","format":"date-time","description":"Session start timestamp (ISO 8601)"},"end_date_time":{"type":"string","format":"date-time","description":"Session end timestamp (ISO 8601)"},"status":{"type":"string","enum":["ChatSessionOpened","ChatSessionClosed"],"description":"Current session status"},"tag":{"type":["string","null"],"description":"Tag associated with this session"},"messages":{"type":"array","description":"Session messages. Only present when includeMessages=true","items":{"$ref":"#/components/schemas/ChatMessage"}}}},"ChatMessage":{"type":"object","description":"A message within a chat session","properties":{"id":{"type":"string","description":"Unique message identifier"},"body":{"type":"string","description":"Message body/content"},"direction":{"type":"string","enum":["inbound","outbound"],"description":"Message direction"},"timestamp":{"type":["string","null"],"format":"date-time","description":"Message timestamp"},"type":{"type":"string","description":"Message type"},"channel":{"type":"string","description":"Channel the message was sent through"},"status":{"type":"string","description":"Message delivery status"}}}}},"paths":{"/chat-sessions/recent":{"get":{"summary":"Get Recent Chat Sessions","description":"Retrieve chat sessions from the past X hours across all contacts belonging to the authenticated user.\nSupports optional filtering by session status and message inclusion.\n","tags":["Chat Sessions"],"parameters":[{"$ref":"#/components/parameters/ApiKeyParam"},{"$ref":"#/components/parameters/UserIdParam"},{"name":"hours","in":"query","required":true,"schema":{"type":"integer","minimum":1},"description":"Number of hours to look back for recent sessions"},{"name":"status","in":"query","required":false,"schema":{"type":"string","enum":["ChatSessionOpened","ChatSessionClosed"]},"description":"Filter sessions by status"},{"name":"limit","in":"query","required":false,"schema":{"type":"integer","default":100,"minimum":1},"description":"Maximum number of sessions to return"},{"name":"includeMessages","in":"query","required":false,"schema":{"type":"boolean","default":false},"description":"Whether to include messages in each session"}],"responses":{"200":{"description":"Recent chat sessions retrieved successfully","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"},"data":{"type":"object","properties":{"hours_ago":{"type":"integer","description":"Number of hours looked back"},"total_sessions":{"type":"integer","description":"Total number of sessions found"},"sessions":{"type":"array","items":{"$ref":"#/components/schemas/RecentChatSession"}}}}}}}}},"400":{"description":"Missing or invalid hours parameter","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"},"error_code":{"type":"integer"},"error":{"type":"string"}}}}}},"401":{"description":"Authentication required or invalid credentials","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"},"error_code":{"type":"integer"},"error":{"type":"string"}}}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"},"error_code":{"type":"integer"},"error":{"type":"string"}}}}}}}}}}}
```

## Get Chat Sessions for Contact

> Retrieve all chat sessions for a specific contact. The contact must belong to the authenticated user.<br>

```json
{"openapi":"3.1.0","info":{"title":"DM Champ API","version":"1.0.0"},"servers":[{"url":"https://api.dmchamp.com/v1","description":"Production API Server"}],"security":[{"ApiKeyAuth":[]},{"UserIdAuth":[]}],"components":{"securitySchemes":{"ApiKeyAuth":{"type":"apiKey","in":"query","name":"apiKey","description":"Your DM Champ API key. Obtain from Settings → API Keys."},"UserIdAuth":{"type":"apiKey","in":"query","name":"userId","description":"Your DM Champ User ID. Alternative to apiKey authentication. Cannot be used for agency-only endpoints."}},"parameters":{"ApiKeyParam":{"name":"apiKey","in":"query","description":"API key for authentication. At least one of apiKey or userId is required for protected endpoints.","required":false,"schema":{"type":"string"}},"UserIdParam":{"name":"userId","in":"query","description":"User ID for authentication. Alternative to apiKey. At least one of apiKey or userId is required for protected endpoints.","required":false,"schema":{"type":"string"}}},"schemas":{"ChatSession":{"type":"object","description":"A chat session between the user and a contact","properties":{"id":{"type":"string","description":"Unique session identifier"},"start_date_time":{"type":"string","format":"date-time","description":"Session start timestamp (ISO 8601)"},"end_date_time":{"type":"string","format":"date-time","description":"Session end timestamp (ISO 8601)"},"status":{"type":"string","enum":["ChatSessionOpened","ChatSessionClosed"],"description":"Current session status"},"tag":{"type":["string","null"],"description":"Tag associated with this session"},"messages":{"type":"array","description":"Session messages. Only present when includeMessages=true","items":{"$ref":"#/components/schemas/ChatMessage"}}}},"ChatMessage":{"type":"object","description":"A message within a chat session","properties":{"id":{"type":"string","description":"Unique message identifier"},"body":{"type":"string","description":"Message body/content"},"direction":{"type":"string","enum":["inbound","outbound"],"description":"Message direction"},"timestamp":{"type":["string","null"],"format":"date-time","description":"Message timestamp"},"type":{"type":"string","description":"Message type"},"channel":{"type":"string","description":"Channel the message was sent through"},"status":{"type":"string","description":"Message delivery status"}}}}},"paths":{"/chat-sessions/{contactId}":{"get":{"summary":"Get Chat Sessions for Contact","description":"Retrieve all chat sessions for a specific contact. The contact must belong to the authenticated user.\n","tags":["Chat Sessions"],"parameters":[{"$ref":"#/components/parameters/ApiKeyParam"},{"$ref":"#/components/parameters/UserIdParam"},{"name":"contactId","in":"path","required":true,"schema":{"type":"string"},"description":"Firestore document ID of the contact"},{"name":"status","in":"query","required":false,"schema":{"type":"string","enum":["ChatSessionOpened","ChatSessionClosed"]},"description":"Filter sessions by status"},{"name":"limit","in":"query","required":false,"schema":{"type":"integer","default":100,"minimum":1},"description":"Maximum number of sessions to return"},{"name":"includeMessages","in":"query","required":false,"schema":{"type":"boolean","default":false},"description":"Whether to include messages in each session"}],"responses":{"200":{"description":"Chat sessions retrieved successfully","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"},"data":{"type":"object","properties":{"contact_id":{"type":"string","description":"Contact identifier"},"contact_name":{"type":"string","description":"Contact full name"},"total_sessions":{"type":"integer","description":"Total number of sessions found"},"sessions":{"type":"array","items":{"$ref":"#/components/schemas/ChatSession"}}}}}}}}},"400":{"description":"Missing required parameters","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"},"error_code":{"type":"integer"},"error":{"type":"string"}}}}}},"401":{"description":"Authentication required or invalid credentials","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"},"error_code":{"type":"integer"},"error":{"type":"string"}}}}}},"403":{"description":"Contact does not belong to authenticated user","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"},"error_code":{"type":"integer"},"error":{"type":"string"}}}}}},"404":{"description":"Contact not found","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"},"error_code":{"type":"integer"},"error":{"type":"string"}}}}}}}}}}}
```