> ## Documentation Index > Fetch the complete documentation index at: https://docs.periskope.app/llms.txt > Use this file to discover all available pages before exploring further. # Create Ticket > Creates a ticket on a chat (chat_id and subject required). Only one ticket can be raised per message. Custom property values cannot be set at creation — use the update endpoint after. ## OpenAPI ````yaml api-reference/openapi-generated.json POST /v1/tickets/create openapi: 3.0.3 info: title: Periskope API version: 1.0.0 description: >- Periskope external API. Responses use a flat, unwrapped shape: most endpoints return the resource at the top level, and list endpoints return a wrapper object with pagination inline (e.g. `{ from, to, count, chats: [...] }`). The documented response schemas describe these shapes directly. servers: - url: https://api.periskope.app security: - bearerAuth: [] paths: /v1/tickets/create: post: tags: - Tickets summary: Create a ticket description: >- Creates a ticket on a chat (chat_id and subject required). Only one ticket can be raised per message. Custom property values cannot be set at creation — use the update endpoint after. operationId: createTicket requestBody: content: application/json: schema: type: object properties: chat_id: type: string minLength: 1 description: >- Chat to raise the ticket on. For group chats, the chat_id ending with @g.us; for 1-1 chats, country code + number of the contact (e.g. 911111111111) or the chat_id suffixed with @c.us. example: 120363000000000000@g.us subject: type: string minLength: 1 description: Subject of the new ticket example: Customer cannot access invoices quoted_message_id: type: string minLength: 1 description: >- message_id (or unique id) of the message in the chat to raise the ticket from. The message must exist in the chat (404 otherwise), and only one ticket can be raised per message — a second create for the same message is rejected. Stored and returned as the unique id of the message. example: >- false_120363000000000000@g.us_AAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA assignee: type: string nullable: true description: >- Email of the member to assign the ticket to. Must be the email of a member of the organization — the request is rejected otherwise. Omit, or pass null or an empty string, to leave the ticket unassigned. example: user@example.com due_date: type: string nullable: true description: >- Due date of the new ticket. Accepts ISO 8601 (e.g. 2026-02-01T00:00:00Z) and any format parseable as a JavaScript date (YYYY-MM-DD, MM/DD/YYYY, etc.). Epoch timestamps are not supported. Omit, or pass null or an empty string, for no due date. example: '2026-02-01' priority: type: string description: >- Priority of the ticket as a string: '1' (low), '2' (medium), '3' (high) or '4' (urgent). An empty string is ignored (the priority is left unchanged/unset). New tickets have no priority unless one is provided. example: '2' status: type: string enum: - open - inprogress - closed - archived description: >- Initial status of the ticket: 'open', 'inprogress', 'closed' or 'archived'. Defaults to 'open'. example: open labels: type: string nullable: true description: >- Comma-separated list of ticket label names to apply, matched case-insensitively. Labels that do not exist yet are created automatically. Omit, or pass null or an empty string, for no labels. example: urgent, billing required: - chat_id - subject responses: '200': description: The created ticket with its chat and quoted message content: application/json: schema: $ref: '#/components/schemas/TicketInfo' examples: default: summary: Response body value: chat: org_id: 00000000-0000-0000-0000-000000000000 chat_id: 120363000000000000@g.us members: key: contact_id: 911111111111@c.us chat_id: 120363000000000000@g.us org_id: 00000000-0000-0000-0000-000000000000 org_phone: 911111111111@c.us is_admin: false is_super_admin: false contact_name: Rahul Sharma contact_image: https://example.com/files/image.png contact_color: '#7D9EF1' is_internal: false contact_labels: vip, billing is_muted: false chat_name: Example Corp Support chat_type: group org_phone: 911111111111@c.us chat_image: https://example.com/files/image.png created_at: '2026-01-10T08:00:00+00:00' chat_labels: customer, priority invite_link: null group_description: null custom_properties: Region: EMEA freshdesk_metadata: {} zohodesk_metadata: {} initiated_by: null is_archived: false parent_community_id: null message: message_id: >- false_120363000000000000@g.us_AAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA chat_id: 120363000000000000@g.us org_phone: 911111111111@c.us timestamp: '2026-01-15T09:28:00+00:00' body: I cannot open my invoices from the portal media_path: '' sender_phone: '911111111111' sender_name: Rahul Sharma performed_by: null ticket: ticket_id: ACM-001 org_id: 00000000-0000-0000-0000-000000000000 subject: Customer cannot access invoices status: open priority: 2 assignee: user@example.com assigned_by: '' raised_by: api due_date: '2026-02-01 00:00:00+00' ticket_labels: urgent, billing ticket_custom_properties: Workspace: Example Corp quoted_message_id: AAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA created_at: '2026-01-15T09:30:00.000Z' closed_at: null closed_by: null closed_message: null first_assigned_at: null is_deleted: false attached_messages: - message_id: >- false_120363000000000000@g.us_AAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA chat_id: 120363000000000000@g.us org_phone: 911111111111@c.us timestamp: '2026-01-15T09:28:00+00:00' body: I cannot open my invoices from the portal media_path: '' sender_phone: '911111111111' sender_name: Rahul Sharma performed_by: null '401': description: Invalid, expired or missing API token content: application/json: examples: error: summary: Invalid, expired or missing API token value: code: UNAUTHORIZED_ERROR message: Invalid bearer auth token status: 401 schema: type: object properties: code: type: string example: UNAUTHORIZED_ERROR message: type: string example: Invalid bearer auth token status: type: integer example: 401 example: code: UNAUTHORIZED_ERROR message: Invalid bearer auth token status: 401 '404': description: quoted_message_id does not match any message in the chat content: application/json: examples: error: summary: quoted_message_id does not match any message in the chat value: code: NOT_FOUND_ERROR message: quoted_message_id does not match any message in the chat status: 404 schema: type: object properties: code: type: string example: NOT_FOUND_ERROR message: type: string example: quoted_message_id does not match any message in the chat status: type: integer example: 404 example: code: NOT_FOUND_ERROR message: quoted_message_id does not match any message in the chat status: 404 '422': description: Request validation failed content: application/json: examples: error: summary: Request validation failed value: code: VALIDATION_ERROR message: Request validation failed status: 422 fields: body.chat_id: message: chat_id is required schema: type: object properties: code: type: string example: VALIDATION_ERROR message: type: string example: Request validation failed status: type: integer example: 422 fields: type: object additionalProperties: type: object properties: message: type: string value: {} example: body.chat_id: message: chat_id is required example: code: VALIDATION_ERROR message: Request validation failed status: 422 fields: body.chat_id: message: chat_id is required '429': description: Rate limit exceeded content: application/json: examples: error: summary: Rate limit exceeded value: code: RATE_LIMIT_ERROR message: You can only make 100 requests per second status: 429 schema: type: object properties: code: type: string example: RATE_LIMIT_ERROR message: type: string example: You can only make 100 requests per second status: type: integer example: 429 example: code: RATE_LIMIT_ERROR message: You can only make 100 requests per second status: 429 '500': description: Internal server error content: application/json: examples: error: summary: Internal server error value: code: UNKNOWN_ERROR message: Internal server error status: 500 schema: type: object properties: code: type: string example: UNKNOWN_ERROR message: type: string example: Internal server error status: type: integer example: 500 example: code: UNKNOWN_ERROR message: Internal server error status: 500 security: - bearerAuth: [] x-codeSamples: - lang: typescript label: TypeScript source: |- import { PeriskopeApi } from '@periskope/periskope-client'; const client = new PeriskopeApi({ authToken: 'YOUR_API_KEY', }); async function main() { const response = await client.tickets.createTicket({ chat_id: '120363000000000000@g.us', subject: 'Customer cannot access invoices', }); console.log(response); } main(); - lang: bash label: cURL source: |- curl -X POST 'https://api.periskope.app/v1/tickets/create' \ -H 'Authorization: Bearer YOUR_API_KEY' \ -H 'Content-Type: application/json' \ -d '{ "chat_id": "120363000000000000@g.us", "subject": "Customer cannot access invoices" }' components: schemas: TicketInfo: type: object properties: chat: $ref: '#/components/schemas/TicketChat' message: $ref: '#/components/schemas/TicketMessage' ticket: $ref: '#/components/schemas/TicketDetails' attached_messages: type: array items: allOf: - $ref: '#/components/schemas/TicketMessage' - description: >- Summary of a WhatsApp message referenced by a ticket — the quoted message the ticket was raised from, or a message attached to the ticket. description: >- Messages attached to the ticket. Populated only by GET /tickets/{ticket_id} — always an empty array in create and update responses. description: >- A ticket together with its chat, the message it was raised from and (on GET /tickets/{ticket_id}) the messages attached to it. TicketChat: type: object properties: org_id: type: string description: Id of the organization the chat belongs to example: 00000000-0000-0000-0000-000000000000 chat_id: type: string description: >- Unique id of the chat — @c.us for 1-1 chats, @g.us for group chats example: 120363000000000000@g.us members: type: object additionalProperties: $ref: '#/components/schemas/TicketChatMember' description: >- Participants of the chat, as a map of contact_id → member. null when no participants are recorded. is_muted: type: boolean description: Whether the chat is muted on the phone example: false chat_name: type: string description: Display name of the chat example: Example Corp Support chat_type: type: string description: 'Type of the chat: ''user'' for 1-1 chats, ''group'' for groups' example: group org_phone: type: string description: >- Org phone (WhatsApp account) the chat belongs to, suffixed with @c.us example: 911111111111@c.us chat_image: type: string description: URL of the chat image, when available example: https://example.com/files/image.png created_at: type: string description: When the chat was created, as an ISO 8601 timestamp example: '2026-01-10T08:00:00+00:00' chat_labels: type: string description: >- Names of the labels applied to the chat, joined with ", ". An empty string when the chat has no labels. example: customer, priority invite_link: type: string description: >- WhatsApp invite link of the group. null for 1-1 chats or when not available. example: null group_description: type: string description: Description of the group. null for 1-1 chats. example: null custom_properties: type: object additionalProperties: type: string description: >- Values of every chat custom property of the workspace, as a map of property name → formatted display value (an empty string for properties not set on this chat). Property definitions are managed via the Properties endpoints (see the CustomProperty component). example: Region: EMEA freshdesk_metadata: type: object description: Sync metadata of the Freshdesk integration, when connected example: {} zohodesk_metadata: type: object description: Sync metadata of the Zoho Desk integration, when connected example: {} initiated_by: type: string description: >- Who initiated the chat, when known (e.g. the org phone or the contact) example: null is_archived: type: boolean description: Whether the chat is archived on the phone example: false parent_community_id: type: string description: >- Id of the parent WhatsApp community when the group belongs to one. null otherwise. example: null description: >- The chat the ticket is raised on. null in the rare case the chat record is no longer available. TicketMessage: type: object properties: message_id: type: string description: >- Unique id of the message. Like every field of this object, null when the ticket has no linked message. example: false_120363000000000000@g.us_AAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA chat_id: type: string description: Chat the message belongs to example: 120363000000000000@g.us org_phone: type: string description: >- Org phone (WhatsApp account) the message was sent or received on, suffixed with @c.us example: 911111111111@c.us timestamp: type: string description: When the message was sent, as an ISO 8601 timestamp example: '2026-01-15T09:28:00+00:00' body: type: string description: >- Text content of the message. An empty string for media-only messages. example: I cannot open my invoices from the portal media_path: type: string description: >- URL of the message attachment. An empty string when the message has no media. example: '' sender_phone: type: string description: >- Phone number of the sender, as country code + number without the @c.us suffix example: '911111111111' sender_name: type: string description: >- Contact name of the sender. An empty string when the sender is not a saved contact. example: Rahul Sharma performed_by: type: string description: >- Who sent the message through Periskope: a member's email or 'api'. null for messages received from WhatsApp. example: null description: >- The message the ticket was raised from (quoted_message_id). Always present as an object — every field in it is null when the ticket is not linked to a message. TicketDetails: type: object properties: ticket_id: type: string description: Unique human-readable id of the ticket example: ACM-001 org_id: type: string description: Id of the organization the ticket belongs to example: 00000000-0000-0000-0000-000000000000 subject: type: string description: Subject of the ticket example: Customer cannot access invoices status: type: string enum: - open - inprogress - closed - archived description: >- Lifecycle status of the ticket: 'open', 'inprogress', 'closed' or 'archived' example: open priority: type: integer description: >- Priority of the ticket: 1 (low), 2 (medium), 3 (high) or 4 (urgent). Tickets with no priority set are reported as 1 here. example: 2 assignee: type: string description: >- Email of the member the ticket is assigned to. An empty string when unassigned. example: user@example.com assigned_by: type: string description: >- Email of the member who assigned the ticket. An empty string when it has not been assigned. example: '' raised_by: type: string description: >- Who raised the ticket: a member's email, or 'api' when created via the API example: api due_date: type: string description: >- Due date of the ticket as a timestamp string (e.g. 2026-02-01 00:00:00+00). An empty string when no due date is set. example: '2026-02-01 00:00:00+00' ticket_labels: type: string description: >- Names of the ticket labels applied to the ticket, joined with ", ". An empty string when the ticket has no labels. example: urgent, billing ticket_custom_properties: type: object additionalProperties: type: string description: >- Values of every ticket custom property of the workspace, as a map of property name → formatted display value (an empty string for properties not set on this ticket; option ids are resolved to their labels). Property definitions are managed via the Properties endpoints (see the CustomProperty component). example: Workspace: Example Corp quoted_message_id: type: string description: >- Unique id of the message the ticket was raised from. null when the ticket is not linked to a message. example: AAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA created_at: type: string description: When the ticket was created, as an ISO 8601 timestamp example: '2026-01-15T09:30:00.000Z' closed_at: type: string description: >- When the ticket was closed, as an ISO 8601 timestamp. null while the ticket is not closed. example: null closed_by: type: string description: >- Who closed the ticket: a member's email, or 'api' when closed via the API without a closed_by value. null while the ticket is not closed. example: null closed_message: type: string description: >- Closing message supplied when the ticket was closed. null while the ticket is not closed or when none was given. example: null first_assigned_at: type: string description: >- When the ticket was first assigned to a member, as an ISO 8601 timestamp. null when it has never been assigned. example: null is_deleted: type: boolean description: Whether the ticket has been deleted example: false description: The ticket itself TicketChatMember: type: object properties: contact_id: type: string description: Contact id of the member, suffixed with @c.us example: 911111111111@c.us chat_id: type: string description: Chat the membership belongs to example: 120363000000000000@g.us org_id: type: string description: Id of the organization example: 00000000-0000-0000-0000-000000000000 org_phone: type: string description: >- Org phone (WhatsApp account) the chat belongs to, suffixed with @c.us example: 911111111111@c.us is_admin: type: boolean description: Whether the member is an admin of the group chat example: false is_super_admin: type: boolean description: Whether the member is the super admin (creator) of the group chat example: false contact_name: type: string description: Saved name of the contact. null when not a saved contact. example: Rahul Sharma contact_image: type: string description: URL of the profile image of the contact, when available example: https://example.com/files/image.png contact_color: type: string description: Hex color assigned to the contact in the dashboard example: '#7D9EF1' is_internal: type: boolean description: >- Whether the contact is an internal (workspace) contact rather than an external customer example: false contact_labels: type: string description: >- Names of the labels applied to the contact, joined with ", ". An empty string when the contact has no labels. example: vip, billing description: A participant of the chat a ticket is raised on. securitySchemes: bearerAuth: type: http scheme: bearer description: >- Your Periskope API token, sent as `Authorization: Bearer `. Generate one from the Periskope dashboard under **Settings → API & Webhooks**. API access requires an active Pro or Enterprise plan. ```` This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.