--- title: Puzzel API Integration on Truto slug: puzzel category: Helpdesk canonical: "https://truto.one/integrations/detail/puzzel/" --- # Puzzel API Integration on Truto **Category:** Helpdesk **Status:** Beta ## MCP-ready AI tools Truto exposes 84 tools for Puzzel that AI agents can call directly. - **list_all_puzzel_user_groups** — List user groups in Puzzel. Returns result with each group including id and name. - **list_all_puzzel_token_info** — Get access token information in Puzzel. Returns customerKey, customerId, userGroupId, userId, languageId, languageCode, passwordValidDaysLeft, and accessTokenExpiry in the response. - **list_all_puzzel_scheduled_tasks** — Search for scheduled tasks in Puzzel. Returns entries with details such as contactId, name, phone, duration, queueId, scheduledDateTime, reservedUserId, reservedUserName, and title. - **get_single_puzzel_scheduled_task_by_id** — Get an existing scheduled task in Puzzel using id. Returns fields such as contactId, name, description, phone, reservedUserId, scheduledDateTime, queueKey, and related variables. - **create_a_puzzel_scheduled_task** — Create a new scheduled-tasks in Puzzel. Returns result and code fields in the response. - **update_a_puzzel_scheduled_task_by_id** — Update a scheduled etask in Puzzel using id. Returns updated etask details such as contactId, name, scheduledDateTime, reservedUserId, and variables. - **delete_a_puzzel_scheduled_task_by_id** — Delete a scheduled task in Puzzel. Requires id. Returns code indicating the result of the operation. - **create_a_puzzel_sm** — Send an SMS message in Puzzel. Requires user_id. Returns code (status), id (message identifier), and message (status message) in the response. - **list_all_puzzel_token_extended_information** — Get extended access token details in Puzzel, including customerKey, userId, accessTokenExpiry, language, pauseTypes, and queues. Returns these fields in the response. - **list_all_puzzel_archive_records** — Search archive records in Puzzel for a specific user. Requires user_id. Returns fields including recordStart, accessPoint, callId, recordingType, contentAvailable, surveyExist, enquiryRegistrationExists, entries, tags, and comment. - **delete_a_puzzel_archive_record_by_id** — Delete an archived record in Puzzel. Requires user_id. Returns code (status), id (record identifier), and message (operation result details) in the response. - **get_single_puzzel_archive_stream_by_id** — Stream archive recordings for a specific user in Puzzel. Requires user_id, iq_session_id, and id. Returns the audio/video stream content for the requested archive recording. - **puzzel_archive_recording_files_download** — Download a recording file from Archive in Puzzel. Requires user_id, iq_session_id, and index. Returns the audio file as application/octet-stream with Content-Disposition header indicating filename. - **get_single_puzzel_enquiry_registration_by_id** — Get enquiry registration for a specific user by callId in Puzzel. Requires user_id, and id. Returns fields including id, time, agentId, agentName, queueKey, queueDescription, categories. - **get_single_puzzel_survey_by_id** — Get survey from Puzzel by user_id and id. Returns survey details including key fields for the specified callId. - **list_all_puzzel_archive_audit_logs** — Search archive audit logs in Puzzel. Returns id, dateTime, operation, iqSessionId, recIndex, mediaType, and userId fields for each log entry in the response. - **update_a_puzzel_archive_tag_by_id** — Update tags for a specific call archive in Puzzel using user_id and id. Returns code, id, and message indicating the update result. - **list_all_puzzel_catalog_timezone** — Get the customer timezone set in the Puzzel database. Returns result, code, id, and message fields in the response. - **update_a_puzzel_catalog_timezone_by_id** — Update the customer timezone in Puzzel. Returns code, id, and message indicating the result of the operation. - **list_all_puzzel_catalog_contacts** — Search catalog-contacts in Puzzel using user_id. Returns id, firstName, lastName, title, info, organizationName, communicationPoints, and other contact details in the response. - **get_single_puzzel_catalog_contact_by_id** — Retrieve a contact by contactId in Puzzel. Requires user_id, and id. Returns fields such as id, firstName, lastName, title, info, services, communicationPoints with status and address, isCalenderBusy, and organization details. - **list_all_puzzel_contacts_appointments** — List all appointments for a specific contact in Puzzel using user_id and contact_id. Returns id, subject, location, beginTime, endTime, description, durationMinute, isPrivate, isAvailable, source, and absence fields. - **create_a_puzzel_contacts_appointment** — Create a new appointment for a contact in Puzzel. Requires user_id, and contact_id. Returns code, id, message, and result fields in the response. - **update_a_puzzel_contacts_appointment_by_id** — Update an existing appointment for a contact in Puzzel. Returns code, id, and message fields indicating the result of the operation. Requires user_id, and contact_id. - **delete_a_puzzel_contacts_appointment_by_id** — Delete an appointment in Puzzel for a specific contact using user_id, contact_id, and id. Returns code, id, and message indicating result. - **list_all_puzzel_access_point_tickers** — Get ticker data for access numbers in Puzzel by ticker_period_window. Returns accesspoint, requestsOffered, and requestsAnswered fields in the response. - **list_all_puzzel_state_information** — Get real-time agent state and statistics for a specific user group in Puzzel. Requires ticker_period_window, and userGroupName. Returns userId, name, status, stats, and survey results fields. - **list_all_puzzel_personal_queue_requests** — List requests in the personal queue for a user in Puzzel. Requires user_id. Returns requestId, serviceId, timeInQueue, vip, mediaType, requestStatus, sla, description, category, callbackScheduledTime, and more for each request. - **list_all_puzzel_connected_requests** — List connected requests for a specific user in Puzzel. Requires user_id. Returns queueName, requestCategory, requestDescription, requestRemoteAddress, durationSeconds, userName, and userId for each connected request. - **list_all_puzzel_user_state_information** — Get user state information in Puzzel by user_id. Returns userStatus, contactCentreStatus, status duration, chat connection details, silent monitoring flags, and related fields in the response. - **list_all_puzzel_extended_user_state_info** — Get very detailed user state information in Puzzel. Requires user_id. Returns userStateInformation, systemDateTime, iqSessionStateInformation, recordingInfo, requestPersonalQueueList, request, and pauseDisabledList fields in the response. - **list_all_puzzel_agents_stats** — Get real-time agent stats in Puzzel for a given user_id, and ticker_period_window. Returns queuesTotal, pause, and overview data including requestsOffered, requestsAnswered, loggedOnSeconds, inPauseSeconds, survey stats, and more. - **list_all_puzzel_user_visual_queues** — List visual queues for a specific user in Puzzel user_id. Returns a list with fields: requestId, serviceId, timeInQueue, vip, mediaType, requestStatus, queueId, and callbackScheduledTime. - **get_single_puzzel_user_visual_queue_by_id** — Get visual queue information in Puzzel for a specific visual queue using user_id, and id. Returns fields such as requestId, serviceId, timeInQueue, mediaType, requestStatus, and destination. - **list_all_puzzel_visual_queues** — List visual-queues in Puzzel. Returns id, description, and queues with id, key, description, and serviceId in the response. - **get_single_puzzel_visual_queue_by_id** — Get user visual queue information in Puzzel for a specific visual queue. Requires id, and result. Returns usersDetails and usersOverview fields with details on users and overall queue status. - **list_all_puzzel_visual_queue_state_info** — Get visual queue state and ticker information in Puzzel. Requires visual_queue_result. Returns id, description, waitTimeMaxSeconds, waitTimeAverageSeconds, queueSize, agentsLoggedOn, agentsInPause, agentsReady, agentsUnavailable, sla, queueSizeCiq, unblockedLoggedIn, unblockedUnavailable, queueSizePreferred, callsOfferedToday, callsAnsweredToday, ciqsOfferedToday, ciqsAnsweredToday, callsAnsweredWithinSla, alarmFlag, ciqScheduled, callsAbandonedToday, callsAbandonedWithinSla, silentCallsToday fields in the response. - **list_all_puzzel_visual_queue_ticker** — Get visual queue ticker information in Puzzel for the specified ticker_period_window, and visual_queue_result. Returns id, description, call statistics, CIQ and survey results in the response. - **get_single_puzzel_etask_by_id** — Get details about a specific etask request in Puzzel. Requires id. Returns id, additionalInfo, requestStart, queueEntryTime, reservedUserExpiry, status, queueId, mediaType, queuePosition, iqSessionId, extendedInformations, from, to, vipScore, reservedUserId, and variables. - **create_a_puzzel_etask** — Add etasks or emails in Puzzel. Returns the created etask object including from, to, subject, uri, vipScore, reservedUserId, reservedUserWaitTime, category, description, variables, queueKey, and xdrCopy fields. - **delete_a_puzzel_etask_by_id** — Delete an existing etask/email request in Puzzel by id. Returns code indicating operation completion. - **update_a_puzzel_etask_by_id** — Update etask or email request in Puzzel. Returns updated fields including subject, uri, vipScore, reservedUserId, reservedSecondsFromNow, category, description, queueKey, variables, and xdrCopy. - **update_a_puzzel_request_by_id** — Update a request in queue by id in Puzzel. Returns code, id, and message fields indicating the result of the operation. - **get_single_puzzel_request_by_id** — Get details about a specific request in Puzzel. Requires id. Returns fields such as remoteAddress, destination, requestStart, status, variables, extendedInformations, and outboundInfo. - **delete_a_puzzel_request_by_id** — Delete a request in Puzzel. Requires id. Returns code, id, and message indicating the operation result. - **list_all_puzzel_missed_calls** — List missed calls in Puzzel for a specific queue using queue_id. Returns key fields for each missed call: queueId, queueName, requestId, requestRemoteAddress, destination, queueEntered, inQueueSeconds, category, description, reservedUserId, mediaType, tagLevel, userIdTagged, userNameTagged, and dateTimeTagged. - **puzzel_missed_calls_tag** — Tag a missed call in Puzzel. Requires missed_call_id. Returns code, id, and message fields indicating the tagging operation result. - **list_all_puzzel_user_missed_calls** — List missed calls for a user in Puzzel by id. Returns fields such as queueId, queueName, requestId, requestRemoteAddress, destination, queueEntered, inQueueSeconds, category, tagLevel, userIdTagged, userNameTagged, dateTimeTagged, and others. - **get_single_puzzel_user_request_by_id** — Get details of a specific user request in Puzzel using id. Returns fields such as remoteAddress, destination, status, queueId, vip, mediaType, variables, and extendedInformations. - **puzzel_user_requests_reserve** — Reserve a user-request in Puzzel by user_id and request id. Returns code, id, and message indicating the reservation result. - **delete_a_puzzel_user_request_by_id** — Cancel a reserved user-request in Puzzel. Requires user_id, and id. Returns code, id, and message indicating the result of the cancellation. - **puzzel_user_requests_events** — Create session request event in Puzzel for a specific user and request. Requires user_id, and request_id. Returns code, id, and message fields in the response indicating the result. - **list_all_puzzel_request_extended_information** — Get extended information about a specific request in Puzzel. Requires request_id. Returns fields: time, message, fullUserName, userId, type, and userName for each entry in the response. - **list_all_puzzel_user_call_logs** — List last 20 request logs for a specific user in Puzzel, including queueName, queueId, accessPoint, requestId, mediaType, callType, requestRemoteAddress, answeredAt, and speakTimeSeconds. Requires user_id. These fields are returned in the response. - **create_a_puzzel_user_callout_request** — Create an outgoing callout request for a user in Puzzel using user_id. Returns callout execution details including destination, scheduling, and agent assignment fields. - **delete_a_puzzel_user_callout_request_by_id** — Delete a specific callout request for a user in Puzzel. Returns code (operation status), id (request id), and message (operation result). - **create_a_puzzel_user_email** — Send an email message for a specific user in Puzzel. Requires user_id. Returns code, id, and message fields indicating the email send status and message id. - **create_a_puzzel_user_enquiry_registration** — Create enquiry registration for a user in Puzzel. Requires user_id. Returns code (status code), id (enquiry registration id), and message (response information). - **list_all_puzzel_enquiry_registrations_categories** — Get enquiry registration categories and topics in Puzzel using user_id, and result. Returns code, id, and message fields in the response. - **list_all_puzzel_outbound_request_feedback** — Update an outbound dialler request with feedback in Puzzel. Requires user_id. Returns code, id, and message indicating the result of the update. - **list_all_puzzel_call_recordings** — Get recording details of the connected call in Puzzel using user_id. Returns recordingIndex, recordingStart, recordingState, forcedOnQueue, forcedOnUser, and lengthSeconds fields. - **puzzel_call_recordings_command** — Send a recorder command for a user session in Puzzel. Requires user_id. Returns code, id, and message indicating the command status. - **puzzel_user_sessions_command** — Execute a command for an active user session in Puzzel using user_id and session_id. Returns code, id, and message indicating the command status. - **list_all_puzzel_languages** — List languages in Puzzel. Returns each language's id, code, and description in the response. - **list_all_puzzel_system_date_time** — Get system date and time in Puzzel. Returns result (system dateTime), code, id, and message in the response. - **list_all_puzzel_system_properties** — Retrieve a list of property settings for a specified property_group in Puzzel. Returns key, value, and typeId for each property. - **create_a_puzzel_system_property** — Set property value for a property group in Puzzel. Requires property_group. Returns code, id, and message fields in the response indicating result and operation info. - **get_single_puzzel_system_property_by_id** — Get details about a system property in Puzzel using property_group, id, and userId. Returns key, value, and typeId fields in the response. - **list_all_puzzel_queues** — List queues in Puzzel. Returns id, key, description, and serviceId for each queue. - **list_all_puzzel_services** — List services in Puzzel. Returns id, number, and description fields for each service in the response. - **list_all_puzzel_service_qualities** — List service qualities in Puzzel. Returns id, number, description, serviceId, and elements (with id, name, userLevel) fields in the response. - **list_all_puzzel_user_service_labels** — List service labels for a specific user in Puzzel. Returns nodeType, label, and nodeId for each service label. - **puzzel_user_service_labels_search** — Search for service labels in Puzzel for a specific user using user_id. Returns nodeType, label, and nodeId for each matched service label. - **list_all_puzzel_access_logs** — List access logs in Puzzel for the last 14 days. Returns entries containing id, dateTime, ip, clientType, clientInfo, logInResult, userId, and userName. - **list_all_puzzel_changelogs** — Search change logs in Puzzel for the past 3 months. Returns entries with id, dateTime, userId, auditType, operation, key, and value for each change. - **puzzel_access_token_logout** — Log out and destroy access token in Puzzel. Returns code, id, and message fields in the response. - **list_all_puzzel_pause_types** — List pause types in Puzzel. Requires userId. Returns id and description for each pause type in the response. - **list_all_puzzel_users_search** — Search for users in Puzzel using user_id. Returns user details such as userGroupName, profileName, chatState, contactCentreStatus, joined, userStatus, sessionTime, and profiles. - **get_single_puzzel_profile_by_id** — Get details of a specific profile for a user in Puzzel using user_id, and id. Returns profile fields including id, number, lastPhoneNumber, phoneNumber, phoneType, name, groupProfile, and qualities. - **create_a_puzzel_profile_element** — Add a quality element/skill to a specific user profile in Puzzel. Requires user_id, and profile_id. Returns code, id, and message indicating the result. - **delete_a_puzzel_profile_element_by_id** — Remove a skill from profile in Puzzel. Requires user_id, profile_id, and id. Returns code, id, and message fields in the response indicating the operation result. - **list_all_puzzel_iq_session_state_info** — Get IQ session state information for a specific user_id in Puzzel. Returns iqSessionId, iqSessionState, requestIds, user session details, and request metadata for the given user_id. - **list_all_puzzel_available_users** — List available users (Ready) in Puzzel for a specific user. Requires user_id. Returns the users who are logged on and available. - **list_all_puzzel_query_users** — Search users by queue or user filter in Puzzel. Requires user_id. Returns sourceSearchResultType, contactCentreStatus, queueDescription, queueKey, userFullName, userId, userName, userStatus, and chatState fields in the response. ## How it works 1. **Link your customer's Puzzel account.** Use Truto's frontend SDK; we handle every OAuth and API key flow so you don't need to create the OAuth app. 2. **Authentication is automatic.** Truto refreshes tokens, stores credentials securely, and injects them into every API request. 3. **Call Truto's API to reach Puzzel.** The Proxy API is a 1-to-1 mapping of the Puzzel API. 4. **Get a unified response format.** Every response uses a single shape, with cursor-based pagination and data in the `result` field. ## Use cases - **Automate call recording ingestion for AI-powered quality assurance** — QA and conversation intelligence platforms can pull completed interaction records and download call recordings from Puzzel to run sentiment analysis, compliance checks, and agent scoring — without requiring manual exports from contact center admins. - **Sync real-time agent and queue telemetry into workforce management tools** — WFM platforms need continuous visibility into agent states, queue depths, and service-level metrics to detect schedule non-adherence and forecast staffing needs. Polling Puzzel's real-time state and ticker endpoints through Truto eliminates the need to build and maintain direct API plumbing. - **Route omnichannel tasks into Puzzel from external business systems** — CRMs, ticketing platforms, and marketing automation tools can programmatically inject work items — emails, web leads, scheduled callbacks — directly into Puzzel's routing engine via eTasks and scheduled tasks, ensuring they're distributed to skilled agents alongside voice calls. - **Build CRM screen-pop and automatic call logging for vertical SaaS** — Vertical CRMs serving government, housing, or financial services can use Puzzel call log and missed call data to auto-populate customer records on incoming calls and generate follow-up tickets when calls are missed, giving agents a single-pane-of-glass experience. - **Push contextual tags and metadata back into Puzzel from analytics platforms** — After processing interactions externally, SaaS products can write enrichment data — such as churn risk scores or compliance flags — back to Puzzel archive records as tags, keeping the contact center's native reporting in sync with third-party insights. ## What you can build - **Nightly call recording sync pipeline** — Automatically fetch archive records via list_all_puzzel_archive_records, filter by date range or user group, and download audio files with puzzel_archive_recording_files_download for offline transcription and analysis. - **Real-time agent adherence dashboard** — Poll list_all_puzzel_user_state_information and list_all_puzzel_extended_user_state_info on a cadence to detect when agents exceed scheduled break or wrap-up durations, surfacing non-adherence alerts in your WFM product. - **Programmatic eTask and scheduled task creation** — Use create_a_puzzel_etask and create_a_puzzel_scheduled_task to inject non-voice work items from your platform directly into Puzzel's skill-based routing engine so they reach the right agent automatically. - **Missed call follow-up automation** — Consume list_all_puzzel_missed_calls and list_all_puzzel_user_missed_calls to auto-generate follow-up tickets or callback requests inside your CRM whenever a customer interaction goes unanswered. - **Live queue volume feed for forecasting models** — Ingest list_all_puzzel_visual_queue_ticker and list_all_puzzel_agents_stats data to power demand forecasting algorithms with real historical and intraday call volume, answer rate, and average wait time metrics. - **Post-interaction archive tagging from external AI** — After scoring or classifying a call externally, write structured tags back to Puzzel using update_a_puzzel_archive_tag_by_id so supervisors can filter and report on AI-derived labels natively inside Puzzel. ## FAQs ### What authentication method does the Puzzel integration use? Puzzel uses token-based authentication. Truto manages the full auth lifecycle including token retrieval and refresh. You can inspect active token details via the list_all_puzzel_token_info and list_all_puzzel_token_extended_information endpoints, and explicitly revoke sessions with puzzel_access_token_logout. ### Can I download actual call recording audio files, or just metadata? Both. Use list_all_puzzel_archive_records to retrieve interaction metadata and then puzzel_archive_recording_files_download to download the raw audio file. You can also stream a specific recording via get_single_puzzel_archive_stream_by_id. ### What real-time data can I poll from Puzzel through Truto? You can access live agent states (list_all_puzzel_user_state_information, list_all_puzzel_extended_user_state_info), queue-level KPIs like calls offered, answered, and average wait time (list_all_puzzel_visual_queue_ticker, list_all_puzzel_visual_queue_state_info), and per-agent performance stats (list_all_puzzel_agents_stats). ### Can I create outbound calls or send SMS through the integration? Yes. Use create_a_puzzel_user_callout_request to trigger an outbound call for a specific agent, and create_a_puzzel_sm to send an outbound SMS. Both are write operations supported through Truto. ### Is there a Unified API available for Puzzel? There is no Unified API mapping for Puzzel yet. All operations use Puzzel-native API endpoints exposed through Truto's proxy layer. This gives you full access to Puzzel-specific features like eTasks, visual queues, and archive recordings without abstraction trade-offs. ### What write-back operations are supported beyond reading data? Truto supports creating, updating, and deleting scheduled tasks and eTasks; creating callout requests, emails, and enquiry registrations for users; updating archive tags; creating and deleting contact appointments; managing system properties and profile elements; and tagging missed calls — covering the most common CRM sync and workflow automation scenarios.