Mobile Ticketing API

Ticket creation and dynamic contact form integration for mobile applications

This guide covers ticket creation and dynamic contact form integration for mobile applications.

Prerequisites

Before using these APIs, configure authentication as described in Mobile Authentication.

---

Create Support Ticket

Creates a support ticket for issues requiring human assistance.

Endpoint: POST /api/sdk/v1/tickets

Content-Type: multipart/form-data

Request Fields

Field	Type	Required	Description
subject	string	Yes	Ticket subject
typology	string	Yes	Issue type: “technical”, “billing”, “general”
priority	string	Yes	Priority: “low”, “medium”, “high”, “urgent”
body	string	Yes	Detailed description of the issue
conversation_id	string	No	UUID to link ticket to existing conversation
custom_fields	JSON string	No	Array of custom field objects
files	files	No	File attachments (max 5 files, 10MB each)
user_email	string	No	Real email for widget/anonymous users
metadata	JSON string	No	Additional metadata
ticket_form_id	string	No	Form configuration ID

Response

{
  "id": "ticket-uuid",
  "ticket_url": "https://your-domain.example.com/tickets/ticket-uuid"
}

Custom Fields Format

[
  {"id": "field-id-1", "value": "selected-value"},
  {"id": "field-id-2", "value": "text-value"}
]

File Upload Constraints:

Constraint	Value
Max files	5 files per request
Max file size	10MB per file
Allowed types	PDF, images (PNG, JPG, JPEG), documents (DOCX, TXT), spreadsheets

---

Contact Form Integration

The contact form system provides dynamic, configurable forms for ticket creation with custom fields, conditional logic, and progressive display.

Overview

The contact form allows you to:

• Fetch dynamically configured form structures from the server
• Display custom fields based on your ticketing system configuration
• Handle conditional field visibility (fields that appear based on other field values)
• Manage hidden fields that should be submitted but not displayed
• Implement progressive disclosure (fields appear as previous fields are completed)
• Collect email addresses from anonymous widget users

---

Get Form Configuration

Fetch the form configuration before displaying the contact form.

Endpoint: GET /api/sdk/v1/config

Response Structure

{
  "id": "config-uuid",
  "ticketForm": {
    "id": "form-uuid",
    "name": "Support Form",
    "description": "Customer support ticket form",
    "showSubject": true,
    "showBody": true,
    "showStatus": false,
    "showPriority": true,
    "showTypology": true,
    "ticketFormFields": [
      {
        "id": "field-uuid",
        "position": 1,
        "ticketField": {
          "id": "ticket-field-uuid",
          "externalId": "custom_field_123",
          "title": "Department",
          "description": "Select your department",
          "active": true,
          "required": true,
          "isHidden": false,
          "conditionalFieldId": null,
          "conditionalFieldValue": null,
          "type": {
            "id": "type-uuid",
            "name": "tagger",
            "value": "tagger"
          },
          "ticketsFieldOptions": [
            {
              "id": "option-uuid",
              "externalId": "dept_sales",
              "name": "Sales",
              "value": "sales",
              "isDefault": false,
              "position": 1,
              "noDisplay": false
            },
            {
              "id": "option-uuid-2",
              "externalId": "dept_support",
              "name": "Technical Support",
              "value": "support",
              "isDefault": true,
              "position": 2,
              "noDisplay": false
            }
          ]
        }
      }
    ]
  }
}

---

Field Types

Type	Description
tagger	Dropdown select field with predefined options
text	Single-line text input
textarea	Multi-line text input
checkbox	Boolean checkbox field
multiselect	Multiple selection dropdown

---

Field Display Logic

Hidden Fields (isHidden: true)

Hidden fields should be rendered as hidden inputs. Their values must be submitted with the form, but they should not be visible to the user.

if (field.isHidden) {
    // Render as hidden input
    // Still include in form submission
}

Conditional Fields

Fields can be conditionally displayed based on the value of another field using conditionalFieldId and conditionalFieldValue.

if (field.conditionalFieldId && field.conditionalFieldValue) {
    const parentFieldValue = customFields[field.conditionalFieldId];
    if (parentFieldValue !== field.conditionalFieldValue) {
        return; // Don't render this field
    }
}

Example Scenario:

• Field A: “Issue Type” (dropdown: Bug, Feature Request, Question)
• Field B: “Bug Severity” (dropdown: Low, Medium, High)
  • conditionalFieldId: ID of Field A
  • conditionalFieldValue: “Bug”
  • This field only appears when “Bug” is selected in Field A

Progressive Field Display

Fields appear progressively based on form completion:

1. Subject field (if showSubject is true)
2. Typology field appears after subject is filled (if showTypology is true)
3. Priority field appears after typology is filled (if showPriority is true)
4. Custom fields appear sequentially after priority is filled
5. Each subsequent custom field appears after the previous field is completed

Field Options

Options in select fields can have special properties:

Property	Description
noDisplay: true	Option exists but should not be shown in the UI
isDefault: true	This option should be pre-selected
position	Determines the order of options in the dropdown

---

Email Collection for Widget Users

When using widget authentication, the system creates anonymous users with email format unknown_ago@{widget-id}.com. To collect the user’s real email:

1. Check if the user is anonymous (email starts with unknown_ago@)
2. Show an email input field in your form
3. Validate the email format
4. Pass the email in the user_email field when submitting the ticket

The real email will be stored separately and used for ticket notifications.

---

Swift (iOS) Implementation

// MARK: - Models

struct TicketForm: Codable {
    let id: String
    let name: String
    let showSubject: Bool
    let showBody: Bool
    let showPriority: Bool
    let showTypology: Bool
    let ticketFormFields: [TicketFormField]
}

struct TicketFormField: Codable {
    let id: String
    let position: Int
    let ticketField: TicketField
}

struct TicketField: Codable {
    let id: String
    let externalId: String?
    let title: String
    let description: String?
    let active: Bool
    let required: Bool
    let isHidden: Bool
    let conditionalFieldId: String?
    let conditionalFieldValue: String?
    let type: TicketFieldType
    let ticketsFieldOptions: [TicketFieldOption]
}

struct TicketFieldType: Codable {
    let name: String
    let value: String
}

struct TicketFieldOption: Codable {
    let id: String
    let name: String
    let value: String
    let isDefault: Bool
    let position: Int?
    let noDisplay: Bool?
}

struct CustomField: Codable {
    let id: String
    let value: String
}

// MARK: - Contact Form Manager

class ContactFormManager {
    let baseURL = "https://your-domain.example.com/api"
    var authToken: String
    var ticketForm: TicketForm?
    var customFieldValues: [String: String] = [:]

    // Fetch form configuration
    func fetchFormConfiguration() async throws -> TicketForm {
        let url = URL(string: "\(baseURL)/sdk/v1/config")!
        var request = URLRequest(url: url)
        request.setValue("Bearer \(authToken)", forHTTPHeaderField: "Authorization")

        let (data, _) = try await URLSession.shared.data(for: request)
        let config = try JSONDecoder().decode(ConfigResponse.self, from: data)
        self.ticketForm = config.ticketForm
        return config.ticketForm
    }

    // Check if field should be displayed
    func shouldDisplayField(_ field: TicketField, previousFieldFilled: Bool) -> Bool {
        if field.isHidden {
            return false
        }

        if let conditionalFieldId = field.conditionalFieldId,
           let conditionalValue = field.conditionalFieldValue {
            let parentValue = customFieldValues[conditionalFieldId]
            if parentValue != conditionalValue {
                return false
            }
        }

        return previousFieldFilled
    }

    // Get field identifier (prefer externalId over id)
    func getFieldIdentifier(_ field: TicketField) -> String {
        return field.externalId ?? field.id
    }

    // Get visible options for a field
    func getVisibleOptions(_ field: TicketField) -> [TicketFieldOption] {
        return field.ticketsFieldOptions
            .filter { !($0.noDisplay ?? false) }
            .sorted { ($0.position ?? 0) < ($1.position ?? 0) }
    }

    // Submit ticket with custom fields
    func submitTicket(
        subject: String,
        typology: String,
        priority: String,
        body: String,
        conversationId: String?,
        files: [Data]? = nil,
        userEmail: String? = nil,
        metadata: [String: Any]? = nil
    ) async throws -> TicketResponse {
        let url = URL(string: "\(baseURL)/sdk/v1/tickets")!
        var request = URLRequest(url: url)
        request.httpMethod = "POST"
        request.setValue("Bearer \(authToken)", forHTTPHeaderField: "Authorization")

        let boundary = UUID().uuidString
        request.setValue("multipart/form-data; boundary=\(boundary)", forHTTPHeaderField: "Content-Type")

        var bodyData = Data()

        // Add basic fields
        bodyData.appendFormField(boundary: boundary, name: "subject", value: subject)
        bodyData.appendFormField(boundary: boundary, name: "typology", value: typology)
        bodyData.appendFormField(boundary: boundary, name: "priority", value: priority)
        bodyData.appendFormField(boundary: boundary, name: "body", value: body)

        // Add optional fields
        if let conversationId = conversationId {
            bodyData.appendFormField(boundary: boundary, name: "conversation_id", value: conversationId)
        }

        // Add custom fields
        if !customFieldValues.isEmpty {
            let customFields = customFieldValues.map { CustomField(id: $0.key, value: $0.value) }
            let customFieldsJSON = try JSONEncoder().encode(customFields)
            let customFieldsString = String(data: customFieldsJSON, encoding: .utf8)!
            bodyData.appendFormField(boundary: boundary, name: "custom_fields", value: customFieldsString)
        }

        // Add user email for widget users
        if let email = userEmail {
            bodyData.appendFormField(boundary: boundary, name: "user_email", value: email)
        }

        // Add ticket form ID
        if let formId = ticketForm?.id {
            bodyData.appendFormField(boundary: boundary, name: "ticket_form_id", value: formId)
        }

        // Add files
        if let files = files {
            for (index, fileData) in files.enumerated() {
                bodyData.appendFile(boundary: boundary, name: "files", filename: "file\(index).jpg", data: fileData)
            }
        }

        bodyData.append("--\(boundary)--\r\n".data(using: .utf8)!)
        request.httpBody = bodyData

        let (responseData, _) = try await URLSession.shared.data(for: request)
        return try JSONDecoder().decode(TicketResponse.self, from: responseData)
    }
}

// Helper extension for multipart form data
extension Data {
    mutating func appendFormField(boundary: String, name: String, value: String) {
        append("--\(boundary)\r\n".data(using: .utf8)!)
        append("Content-Disposition: form-data; name=\"\(name)\"\r\n\r\n".data(using: .utf8)!)
        append("\(value)\r\n".data(using: .utf8)!)
    }

    mutating func appendFile(boundary: String, name: String, filename: String, data: Data) {
        append("--\(boundary)\r\n".data(using: .utf8)!)
        append("Content-Disposition: form-data; name=\"\(name)\"; filename=\"\(filename)\"\r\n".data(using: .utf8)!)
        append("Content-Type: application/octet-stream\r\n\r\n".data(using: .utf8)!)
        append(data)
        append("\r\n".data(using: .utf8)!)
    }
}

---

Kotlin (Android) Implementation

// MARK: - Models

data class TicketForm(
    val id: String,
    val name: String,
    val showSubject: Boolean,
    val showBody: Boolean,
    val showPriority: Boolean,
    val showTypology: Boolean,
    val ticketFormFields: List<TicketFormField>
)

data class TicketFormField(
    val id: String,
    val position: Int,
    val ticketField: TicketField
)

data class TicketField(
    val id: String,
    val externalId: String?,
    val title: String,
    val description: String?,
    val active: Boolean,
    val required: Boolean,
    val isHidden: Boolean,
    val conditionalFieldId: String?,
    val conditionalFieldValue: String?,
    val type: TicketFieldType,
    val ticketsFieldOptions: List<TicketFieldOption>
)

data class TicketFieldType(
    val name: String,
    val value: String
)

data class TicketFieldOption(
    val id: String,
    val name: String,
    val value: String,
    val isDefault: Boolean,
    val position: Int?,
    val noDisplay: Boolean?
)

data class CustomField(
    val id: String,
    val value: String
)

data class TicketResponse(
    val id: String,
    val ticket_url: String
)

// MARK: - Contact Form Manager

class ContactFormManager(private val authToken: String) {
    private val baseURL = "https://your-domain.example.com/api"
    private val client = OkHttpClient()
    private val gson = Gson()

    var ticketForm: TicketForm? = null
    val customFieldValues = mutableMapOf<String, String>()

    // Fetch form configuration
    suspend fun fetchFormConfiguration(): TicketForm {
        val request = Request.Builder()
            .url("$baseURL/sdk/v1/config")
            .header("Authorization", "Bearer $authToken")
            .build()

        return withContext(Dispatchers.IO) {
            val response = client.newCall(request).execute()
            val json = response.body?.string()
            val config = gson.fromJson(json, ConfigResponse::class.java)
            ticketForm = config.ticketForm
            config.ticketForm
        }
    }

    // Check if field should be displayed
    fun shouldDisplayField(field: TicketField, previousFieldFilled: Boolean): Boolean {
        if (field.isHidden) {
            return false
        }

        if (field.conditionalFieldId != null && field.conditionalFieldValue != null) {
            val parentValue = customFieldValues[field.conditionalFieldId]
            if (parentValue != field.conditionalFieldValue) {
                return false
            }
        }

        return previousFieldFilled
    }

    // Get field identifier (prefer externalId over id)
    fun getFieldIdentifier(field: TicketField): String {
        return field.externalId ?: field.id
    }

    // Get visible options for a field
    fun getVisibleOptions(field: TicketField): List<TicketFieldOption> {
        return field.ticketsFieldOptions
            .filter { !(it.noDisplay ?: false) }
            .sortedBy { it.position ?: 0 }
    }

    // Submit ticket with custom fields
    suspend fun submitTicket(
        subject: String,
        typology: String,
        priority: String,
        body: String,
        conversationId: String? = null,
        files: List<File>? = null,
        userEmail: String? = null,
        metadata: Map<String, Any>? = null
    ): TicketResponse {
        val formBody = MultipartBody.Builder()
            .setType(MultipartBody.FORM)
            .addFormDataPart("subject", subject)
            .addFormDataPart("typology", typology)
            .addFormDataPart("priority", priority)
            .addFormDataPart("body", body)

        conversationId?.let { formBody.addFormDataPart("conversation_id", it) }

        if (customFieldValues.isNotEmpty()) {
            val customFields = customFieldValues.map { CustomField(it.key, it.value) }
            val customFieldsJSON = gson.toJson(customFields)
            formBody.addFormDataPart("custom_fields", customFieldsJSON)
        }

        userEmail?.let { formBody.addFormDataPart("user_email", it) }
        ticketForm?.id?.let { formBody.addFormDataPart("ticket_form_id", it) }

        files?.forEach { file ->
            val requestBody = file.asRequestBody("application/octet-stream".toMediaType())
            formBody.addFormDataPart("files", file.name, requestBody)
        }

        val request = Request.Builder()
            .url("$baseURL/sdk/v1/tickets")
            .header("Authorization", "Bearer $authToken")
            .post(formBody.build())
            .build()

        return withContext(Dispatchers.IO) {
            val response = client.newCall(request).execute()
            val json = response.body?.string()
            gson.fromJson(json, TicketResponse::class.java)
        }
    }
}

---

Best Practices

Form Validation

• Validate required fields before submission
• Show error messages clearly for each field
• Validate email format for widget users
• Check custom field requirements from the form configuration

Progressive Disclosure

• Implement the progressive display logic to avoid overwhelming users
• Show fields only when previous fields are completed
• Use conditional logic to show/hide fields based on other selections

Hidden Fields

• Always render hidden fields as hidden inputs
• Include hidden field values in form submission
• Don’t show hidden fields in the UI but ensure their values are submitted

Field Identifiers

• Always prefer externalId over id for custom field identification
• This ensures compatibility with external ticketing systems (Zendesk, HelpScout)

Widget Users

• Detect anonymous users (email starts with unknown_ago@)
• Collect real email addresses for proper ticket notifications
• Validate email format before submission

Error Handling

• Handle network failures gracefully
• Show user-friendly error messages
• Retry failed submissions
• Validate data before submission to minimize errors

User Experience

• Pre-select default option values where specified
• Show loading indicators during form submission
• Provide clear success/failure feedback
• Auto-save form data to prevent data loss

---

Related Documentation

• Mobile Authentication - Authentication setup
• Mobile Messaging API - Send and receive messages
• Mobile SDK Examples - Complete implementation examples
• Form Configuration API - Full form configuration reference
• Ticketing API - Complete ticketing API reference