talon-one/talon-one-client

Use the Talon.One API to integrate with your application and to manage applications and campaigns: - Use the operations in the [Integration API section](#integration-api) are used to integrate with our platform - Use the operation in the [Management API section](#management-api) to manage applicati

4.0.0 2022-11-16 17:27 UTC

README

Use the Talon.One API to integrate with your application and to manage applications and campaigns:

Determining the base URL of the endpoints

The API is available at the same hostname as your Campaign Manager deployment. For example, if you are reading this page at https://mycompany.talon.one/docs/api/, the URL for the updateCustomerSession endpoint is https://mycompany.talon.one/v2/customer_sessions/{Id}

This PHP package is automatically generated by the OpenAPI Generator project:

  • API version: 1.0.0
  • Package version: 4.0.0
  • Build package: org.openapitools.codegen.languages.PhpClientCodegen

Requirements

PHP 7.1 and later

Installation and usage

You have 2 options:

  • Using Composer (recommended).
  • Using the release's source code.

Using Composer

This is the recommended method.

  1. Install Composer following the installation instructions.

  2. Execute the following command in your project root to install this library:

    composer require talon-one/talon-one-client
  3. Include the autoloader:

    require_once '/path/to/your-project/vendor/autoload.php';

Using the release's source

If you prefer not to use Composer, you can download the package in its entirety. The Releases page lists all stable versions.

  1. Download the source code of the desired version, or checkout the source code directly from the repository.

  2. Uncompress the zip file you downloaded, and include the autoloader in your project:

    require_once '/path/to/talon-one-client/vendor/autoload.php';

Running the tests

To run the unit tests:

composer install
./vendor/bin/phpunit

Getting Started

  1. Follow the installation procedure.
  2. Use the Integration API or the Management API as shown in the following sections.

Integration API

Note: The Integration API's V1 Update customer session and Update customer profile endpoints are now deprecated. Use their V2 instead. See Migrating to V2 for more information.

<?php
require_once(__DIR__ . '/vendor/autoload.php');


// Configure Host, API key, & API key prefix for integration authentication
$config = \TalonOne\Client\Configuration::getDefaultConfiguration()
    ->setHost('https://mycompany.talon.one')
    ->setApiKeyPrefix('Authorization', 'ApiKey-v1')
    ->setApiKey('Authorization', 'dbc644d33aa74d582bd9479c59e16f970fe13bf34a208c39d6c7fa7586968468');

// Initiating an integration api instance with the config
$apiInstance = new \TalonOne\Client\Api\IntegrationApi(
    // If you want use custom http client, pass your client which implements `GuzzleHttp\ClientInterface`.
    // This is optional, `GuzzleHttp\Client` will be used as default when `null` is passed.
    null, // new YouClientImplementation(),
    $config
);

$customer_session_id = 'customer_session_id_example'; // string | The unique identifier for this session
$customer_session = new \TalonOne\Client\Model\NewCustomerSessionV2([
    'profileId' => 'example_prof_id',
    'couponCodes' => [
        'Cool-Summer!'
    ],
    'cartItems' => [
        new \TalonOne\Client\Model\CartItem([
            'name' => 'Hawaiian Pizza',
            'sku' => 'piz-hw-001',
            'quantity' => 1,
            'price' => 5.85
        ])
    ]
]);
$body = new \TalonOne\Client\Model\IntegrationRequest([
    'customerSession' => $customer_session,
    // Optional list of requested information to be present on the response.
    // See lib/Model/IntegrationRequest.php#getResponseContentAllowableValues for full list
    // 'responseContent' => [
    //     \TalonOne\Client\Model\IntegrationRequest::RESPONSE_CONTENT_CUSTOMER_SESSION,
    //     \TalonOne\Client\Model\IntegrationRequest::RESPONSE_CONTENT_COUPONS
    // ]
]);

try {
    // Create/Update a customer session using `updateCustomerSessionV2` function
    $integration_state = $apiInstance->updateCustomerSessionV2($customer_session_id, $body);
    print_r($integration_state);

    // Parsing the returned effects list, please consult https://developers.talon.one/Integration-API/handling-effects-v2 for the full list of effects and their corresponding properties
    foreach ($integration_state->getEffects() as $effect) {
        if ("addLoyaltyPoints" == $effect->getEffectType()) {
            // Initiating right props instance according to the effect type
            $props = new \TalonOne\Client\Model\AddLoyaltyPointsEffectProps((array) $effect->getProps());

            // Access the specific effect's properties
            echo $props->getName(), ':: ', $props->getRecipientIntegrationId(), ' just earned ',  $props->getValue(), ' points', PHP_EOL;
        }
        if ("acceptCoupon" == $effect->getEffectType()) {
            // Initiating right props instance according to the effect type
            $props = new \TalonOne\Client\Model\AcceptCouponEffectProps((array) $effect->getProps());
            // work with AcceptCouponEffectProps' properties
            // ...
        }
    }
} catch (Exception $e) {
    echo 'Exception when calling IntegrationApi->updateCustomerSessionV2: ', $e->getMessage(), PHP_EOL;
}

?>

Management API

<?php
require_once(__DIR__ . '/vendor/autoload.php');


// Configure Host & API key prefix for management authentication
$config = \TalonOne\Client\Configuration::getDefaultConfiguration()
    ->setHost('https://mycompany.talon.one')
    ->setApiKeyPrefix('Authorization', 'Bearer');

// Initiating a management api instance with the config
$apiInstance = new \TalonOne\Client\Api\ManagementApi(
    // If you want use custom http client, pass your client which implements `GuzzleHttp\ClientInterface`.
    // This is optional, `GuzzleHttp\Client` will be used as default when `null` is passed.
    null, // new YouClientImplementation(),
    $config
);

try {
    $loginParams = new \TalonOne\Client\Model\LoginParams([
        'email' => 'admin@talon.one',
        'password' => 'VerySecurePa$$word!'
    ]);

    // create a session (login) in order to get a token
    $session = $apiInstance->createSession($loginParams);

    // Save token in the configuration as API key
    $config->setApiKey('Authorization', $session->getToken());

    $application_id = 7; // int | desired application identifier
    // Calling `getApplication` function
    $application = $apiInstance->getApplication($application_id);
    print_r($application);
} catch (Exception $e) {
    echo 'Exception when calling ManagementApi->getApplication: ', $e->getMessage(), PHP_EOL;
}

?>

Documentation for API Endpoints

All URIs are relative to https://yourbaseurl.talon.one

Class Method HTTP request Description
IntegrationApi createAudienceV2 POST /v2/audiences Create audience
IntegrationApi createCouponReservation POST /v1/coupon_reservations/{couponValue} Create coupon reservation
IntegrationApi createReferral POST /v1/referrals Create referral code for an advocate
IntegrationApi createReferralsForMultipleAdvocates POST /v1/referrals_for_multiple_advocates Create referral codes for multiple advocates
IntegrationApi deleteAudienceMembershipsV2 DELETE /v2/audiences/{audienceId}/memberships Delete audience memberships
IntegrationApi deleteAudienceV2 DELETE /v2/audiences/{audienceId} Delete audience
IntegrationApi deleteCouponReservation DELETE /v1/coupon_reservations/{couponValue} Delete coupon reservations
IntegrationApi deleteCustomerData DELETE /v1/customer_data/{integrationId} Delete customer's personal data
IntegrationApi getCustomerInventory GET /v1/customer_profiles/{integrationId}/inventory List customer data
IntegrationApi getCustomerSession GET /v2/customer_sessions/{customerSessionId} Get customer session
IntegrationApi getLoyaltyTransactions GET /v1/loyalty_programs/{loyaltyProgramId}/profile/{integrationId}/transactions Get loyalty ledger transaction logs
IntegrationApi getReservedCustomers GET /v1/coupon_reservations/customerprofiles/{couponValue} List customers that have this coupon reserved
IntegrationApi returnCartItems POST /v2/customer_sessions/{customerSessionId}/returns Return cart items
IntegrationApi syncCatalog PUT /v1/catalogs/{catalogId}/sync Sync cart item catalog
IntegrationApi trackEvent POST /v1/events Track event
IntegrationApi trackEventV2 POST /v2/events Track event V2
IntegrationApi updateAudienceCustomersAttributes PUT /v2/audience_customers/{audienceId}/attributes Update profile attributes for all customers in audience
IntegrationApi updateAudienceV2 PUT /v2/audiences/{audienceId} Update audience name
IntegrationApi updateCustomerProfileAudiences POST /v2/customer_audiences Update multiple customer profiles' audiences
IntegrationApi updateCustomerProfileV2 PUT /v2/customer_profiles/{integrationId} Update customer profile
IntegrationApi updateCustomerProfilesV2 PUT /v2/customer_profiles Update multiple customer profiles
IntegrationApi updateCustomerSessionV2 PUT /v2/customer_sessions/{customerSessionId} Update customer session
ManagementApi addLoyaltyPoints PUT /v1/loyalty_programs/{loyaltyProgramId}/profile/{integrationId}/add_points Add points in loyalty program for given customer
ManagementApi copyCampaignToApplications POST /v1/applications/{applicationId}/campaigns/{campaignId}/copy Copy the campaign into the specified application
ManagementApi createAccountCollection POST /v1/collections Create account-level collection
ManagementApi createAdditionalCost POST /v1/additional_costs Create additional cost
ManagementApi createAttribute POST /v1/attributes Create custom attribute
ManagementApi createCampaignFromTemplate POST /v1/applications/{applicationId}/create_campaign_from_template Create campaign from campaign template
ManagementApi createCollection POST /v1/applications/{applicationId}/campaigns/{campaignId}/collections Create collection
ManagementApi createCoupons POST /v1/applications/{applicationId}/campaigns/{campaignId}/coupons Create coupons
ManagementApi createCouponsAsync POST /v1/applications/{applicationId}/campaigns/{campaignId}/coupons_async Create coupons asynchronously
ManagementApi createCouponsForMultipleRecipients POST /v1/applications/{applicationId}/campaigns/{campaignId}/coupons_with_recipients Create coupons for multiple recipients
ManagementApi createNotificationWebhook POST /v1/applications/{applicationId}/notification_webhooks Create notification webhook
ManagementApi createPasswordRecoveryEmail POST /v1/password_recovery_emails Request a password reset
ManagementApi createSession POST /v1/sessions Create session
ManagementApi deleteAccountCollection DELETE /v1/collections/{collectionId} Delete account-level collection
ManagementApi deleteCampaign DELETE /v1/applications/{applicationId}/campaigns/{campaignId} Delete campaign
ManagementApi deleteCollection DELETE /v1/applications/{applicationId}/campaigns/{campaignId}/collections/{collectionId} Delete collection
ManagementApi deleteCoupon DELETE /v1/applications/{applicationId}/campaigns/{campaignId}/coupons/{couponId} Delete coupon
ManagementApi deleteCoupons DELETE /v1/applications/{applicationId}/campaigns/{campaignId}/coupons Delete coupons
ManagementApi deleteNotificationWebhook DELETE /v1/applications/{applicationId}/notification_webhooks/{notificationWebhookId} Delete notification webhook
ManagementApi deleteReferral DELETE /v1/applications/{applicationId}/campaigns/{campaignId}/referrals/{referralId} Delete referral
ManagementApi destroySession DELETE /v1/sessions Destroy session
ManagementApi exportAccountCollectionItems GET /v1/collections/{collectionId}/export Export account-level collection's items
ManagementApi exportCollectionItems GET /v1/applications/{applicationId}/campaigns/{campaignId}/collections/{collectionId}/export Export a collection's items
ManagementApi exportCoupons GET /v1/applications/{applicationId}/export_coupons Export coupons
ManagementApi exportCustomerSessions GET /v1/applications/{applicationId}/export_customer_sessions Export customer sessions
ManagementApi exportEffects GET /v1/applications/{applicationId}/export_effects Export triggered effects
ManagementApi exportLoyaltyBalance GET /v1/loyalty_programs/{loyaltyProgramId}/export_customer_balance Export customer loyalty balance to a CSV file
ManagementApi exportLoyaltyLedger GET /v1/loyalty_programs/{loyaltyProgramId}/profile/{integrationId}/export_log Export a customer's loyalty ledger log
ManagementApi exportReferrals GET /v1/applications/{applicationId}/export_referrals Export referrals
ManagementApi getAccessLogsWithoutTotalCount GET /v1/applications/{applicationId}/access_logs/no_total Get access logs for Application
ManagementApi getAccount GET /v1/accounts/{accountId} Get account details
ManagementApi getAccountAnalytics GET /v1/accounts/{accountId}/analytics Get account analytics
ManagementApi getAccountCollection GET /v1/collections/{collectionId} Get account-level collection
ManagementApi getAdditionalCost GET /v1/additional_costs/{additionalCostId} Get additional cost
ManagementApi getAdditionalCosts GET /v1/additional_costs List additional costs
ManagementApi getAllAccessLogs GET /v1/access_logs List access logs
ManagementApi getAllRoles GET /v1/roles List roles
ManagementApi getApplication GET /v1/applications/{applicationId} Get application
ManagementApi getApplicationApiHealth GET /v1/applications/{applicationId}/health_report Get report of health of application API
ManagementApi getApplicationCustomer GET /v1/applications/{applicationId}/customers/{customerId} Get application's customer
ManagementApi getApplicationCustomerFriends GET /v1/applications/{applicationId}/profile/{integrationId}/friends List friends referred by customer profile
ManagementApi getApplicationCustomers GET /v1/applications/{applicationId}/customers List application's customers
ManagementApi getApplicationCustomersByAttributes POST /v1/applications/{applicationId}/customer_search List application customers matching the given attributes
ManagementApi getApplicationEventTypes GET /v1/applications/{applicationId}/event_types List Applications event types
ManagementApi getApplicationEventsWithoutTotalCount GET /v1/applications/{applicationId}/events/no_total List Applications events
ManagementApi getApplicationSession GET /v1/applications/{applicationId}/sessions/{sessionId} Get Application session
ManagementApi getApplicationSessions GET /v1/applications/{applicationId}/sessions List Application sessions
ManagementApi getApplications GET /v1/applications List applications
ManagementApi getAttribute GET /v1/attributes/{attributeId} Get custom attribute
ManagementApi getAttributes GET /v1/attributes List custom attributes
ManagementApi getAudiences GET /v1/audiences List audiences
ManagementApi getCampaign GET /v1/applications/{applicationId}/campaigns/{campaignId} Get campaign
ManagementApi getCampaignAnalytics GET /v1/applications/{applicationId}/campaigns/{campaignId}/analytics Get analytics of campaigns
ManagementApi getCampaignByAttributes POST /v1/applications/{applicationId}/campaigns_search List campaigns that match the given attributes
ManagementApi getCampaigns GET /v1/applications/{applicationId}/campaigns List campaigns
ManagementApi getChanges GET /v1/changes Get audit logs for an account
ManagementApi getCollection GET /v1/applications/{applicationId}/campaigns/{campaignId}/collections/{collectionId} Get collection
ManagementApi getCollectionItems GET /v1/collections/{collectionId}/items Get collection items
ManagementApi getCouponsWithoutTotalCount GET /v1/applications/{applicationId}/campaigns/{campaignId}/coupons/no_total List coupons
ManagementApi getCustomerActivityReport GET /v1/applications/{applicationId}/customer_activity_reports/{customerId} Get customer's activity report
ManagementApi getCustomerActivityReportsWithoutTotalCount GET /v1/applications/{applicationId}/customer_activity_reports/no_total Get Activity Reports for Application Customers
ManagementApi getCustomerAnalytics GET /v1/applications/{applicationId}/customers/{customerId}/analytics Get customer's analytics report
ManagementApi getCustomerProfile GET /v1/customers/{customerId} Get customer profile
ManagementApi getCustomerProfiles GET /v1/customers/no_total List customer profiles
ManagementApi getCustomersByAttributes POST /v1/customer_search/no_total List customer profiles matching the given attributes
ManagementApi getEventTypes GET /v1/event_types List event types
ManagementApi getExports GET /v1/exports Get exports
ManagementApi getLoyaltyPoints GET /v1/loyalty_programs/{loyaltyProgramId}/profile/{integrationId} Get the Loyalty Ledger for this integrationID
ManagementApi getLoyaltyProgram GET /v1/loyalty_programs/{loyaltyProgramId} Get loyalty program
ManagementApi getLoyaltyPrograms GET /v1/loyalty_programs List loyalty programs
ManagementApi getLoyaltyStatistics GET /v1/loyalty_programs/{loyaltyProgramId}/statistics Get loyalty program statistics by loyalty program ID
ManagementApi getNotificationWebhook GET /v1/applications/{applicationId}/notification_webhooks/{notificationWebhookId} Get notification webhook
ManagementApi getNotificationWebhooks GET /v1/applications/{applicationId}/notification_webhooks List notification webhooks
ManagementApi getReferralsWithoutTotalCount GET /v1/applications/{applicationId}/campaigns/{campaignId}/referrals/no_total List referrals
ManagementApi getRole GET /v1/roles/{roleId} Get role
ManagementApi getRuleset GET /v1/applications/{applicationId}/campaigns/{campaignId}/rulesets/{rulesetId} Get ruleset
ManagementApi getRulesets GET /v1/applications/{applicationId}/campaigns/{campaignId}/rulesets List campaign rulesets
ManagementApi getUser GET /v1/users/{userId} Get user
ManagementApi getUsers GET /v1/users List users in account
ManagementApi getWebhook GET /v1/webhooks/{webhookId} Get webhook
ManagementApi getWebhookActivationLogs GET /v1/webhook_activation_logs List webhook activation log entries
ManagementApi getWebhookLogs GET /v1/webhook_logs List webhook log entries
ManagementApi getWebhooks GET /v1/webhooks List webhooks
ManagementApi importAccountCollection POST /v1/collections/{collectionId}/import Import data in existing account-level collection
ManagementApi importAllowedList POST /v1/attributes/{attributeId}/allowed_list/import Import allowed values for attribute
ManagementApi importCollection POST /v1/applications/{applicationId}/campaigns/{campaignId}/collections/{collectionId}/import Import data in existing collection
ManagementApi importCoupons POST /v1/applications/{applicationId}/campaigns/{campaignId}/import_coupons Import coupons
ManagementApi importLoyaltyPoints POST /v1/loyalty_programs/{loyaltyProgramId}/import_points Import loyalty points
ManagementApi importPoolGiveaways POST /v1/giveaways/pools/{poolId}/import Import giveaway codes into a giveaway pool
ManagementApi importReferrals POST /v1/applications/{applicationId}/campaigns/{campaignId}/import_referrals Import referrals
ManagementApi listAccountCollections GET /v1/collections List collections in account
ManagementApi listCollections GET /v1/applications/{applicationId}/campaigns/{campaignId}/collections List collections
ManagementApi listCollectionsInApplication GET /v1/applications/{applicationId}/collections List collections in application
ManagementApi removeLoyaltyPoints PUT /v1/loyalty_programs/{loyaltyProgramId}/profile/{integrationId}/deduct_points Deduct points in loyalty program for given customer
ManagementApi resetPassword POST /v1/reset_password Reset password
ManagementApi searchCouponsAdvancedApplicationWideWithoutTotalCount POST /v1/applications/{applicationId}/coupons_search_advanced/no_total List coupons that match the given attributes (without total count)
ManagementApi searchCouponsAdvancedWithoutTotalCount POST /v1/applications/{applicationId}/campaigns/{campaignId}/coupons_search_advanced/no_total List coupons that match the given attributes in campaign (without total count)
ManagementApi updateAccountCollection PUT /v1/collections/{collectionId} Update account-level collection
ManagementApi updateAdditionalCost PUT /v1/additional_costs/{additionalCostId} Update additional cost
ManagementApi updateAttribute PUT /v1/attributes/{attributeId} Update custom attribute
ManagementApi updateCampaign PUT /v1/applications/{applicationId}/campaigns/{campaignId} Update campaign
ManagementApi updateCollection PUT /v1/applications/{applicationId}/campaigns/{campaignId}/collections/{collectionId} Update collection description
ManagementApi updateCoupon PUT /v1/applications/{applicationId}/campaigns/{campaignId}/coupons/{couponId} Update coupon
ManagementApi updateCouponBatch PUT /v1/applications/{applicationId}/campaigns/{campaignId}/coupons Update coupons
ManagementApi updateNotificationWebhook PUT /v1/applications/{applicationId}/notification_webhooks/{notificationWebhookId} Update notification webhook
ManagementApi updateReferral PUT /v1/applications/{applicationId}/campaigns/{campaignId}/referrals/{referralId} Update referral

Documentation For Models

Documentation For Authorization

api_key_v1

  • Type: API key
  • API key parameter name: Authorization
  • Location: HTTP header

manager_auth

  • Type: API key
  • API key parameter name: Authorization
  • Location: HTTP header

Author