Create PimiDesk tickets from WordPress

At the end, a form on your WordPress site opens a ticket in your PimiDesk workspace.

What you need

• A PimiDesk workspace on a paid plan. A workspace in its trial can reply to mail but cannot create tickets, so this call is refused until the trial ends.
• An API token with write access. Create one on the API Tokens page in the user menu. A read-only or drafts-only token cannot create tickets.
• Your workspace ID. GET /api/v1/workspaces lists the workspaces your token can use, with their ids.
• A place for a few lines of PHP on the WordPress site: a small plugin of your own, or a code snippets plugin.

1. Store the token outside the database

Put the token and the workspace ID in wp-config.php, so they are not in a settings page or an export.

// wp-config.php
define( 'PIMIDESK_TOKEN', 'your-api-token' );
define( 'PIMIDESK_WORKSPACE_ID', 123 );

2. Add a function that opens a ticket

The ticket endpoint needs a subject, a description and a priority (low, medium or high), plus the customer as contact with a name and an email address. PimiDesk finds the contact by email or creates one.

/**
 * Open a PimiDesk ticket for a form submission.
 *
 * @return true|WP_Error
 */
function pimidesk_create_ticket( $name, $email, $subject, $message ) {
    $response = wp_remote_post(
        'https://desk-api.pimi.io/api/v1/workspaces/' . PIMIDESK_WORKSPACE_ID . '/tickets',
        array(
            'timeout' => 10,
            'headers' => array(
                'Authorization' => 'Bearer ' . PIMIDESK_TOKEN,
                'Content-Type'  => 'application/json',
                'Accept'        => 'application/json',
            ),
            'body'    => wp_json_encode(
                array(
                    'subject'     => $subject,
                    'description' => $message,
                    'priority'    => 'medium',
                    'contact'     => array(
                        'name'  => $name,
                        'email' => $email,
                    ),
                )
            ),
        )
    );

    if ( is_wp_error( $response ) ) {
        return $response;
    }

    $code = wp_remote_retrieve_response_code( $response );
    if ( 201 !== $code ) {
        return new WP_Error( 'pimidesk_' . $code, wp_remote_retrieve_body( $response ) );
    }

    return true;
}

3. Call it when your form is submitted

Every form plugin has a hook that runs after a submission. This is the one for Contact Form 7. Change the field names to match your form.

// Contact Form 7, with its default field names.
add_action( 'wpcf7_mail_sent', function () {
    $submission = WPCF7_Submission::get_instance();
    if ( ! $submission ) {
        return;
    }
    $data = $submission->get_posted_data();

    $result = pimidesk_create_ticket(
        $data['your-name'] ?? '',
        $data['your-email'] ?? '',
        $data['your-subject'] ?? 'Website enquiry',
        $data['your-message'] ?? ''
    );

    if ( is_wp_error( $result ) ) {
        error_log( 'PimiDesk: ' . $result->get_error_message() );
    }
} );

Check that it worked

1. Submit the form on your site with an address you can read.
2. Open Tickets in the PimiDesk dashboard. The ticket is there, with the sender as its contact.
3. Check the mailbox you used. PimiDesk sends the customer a confirmation email for a new ticket, unless you have switched that off in the workspace settings.

What goes wrong

A form on a public page attracts spam. Keep your form plugin's spam protection on, so junk submissions do not become tickets.

What this does not do

It does not send your site's own mail, such as password resets or order emails, through PimiDesk. There is no endpoint for that.

Related

• API Reference — every field of the ticket endpoint
• Webhooks — tell your site when a ticket changes
• Getting Started — set up the workspace first