NAME

WebService::Intercom - interact with the Intercom.io API

SYNOPSIS

  my $intercom = WebService::Intercom->new(app_id => '[APP ID]',
                                           api_key => '[API KEY]');

  # Create a user
  my $user = $intercom->user_create_or_update(
     email => 'test@example.com', 
     name => 'test user');
  
  # Retrieve an existing user.
  my $existing_user = $intercom->user_get(email => 'test2@example.com');

  # Add a tag to a user
  $user->tag('test tag');
  $intercom->tag_create_or_update(name => "test tag");
  $intercom->tag_items(name => "test tag", users => [{ email => 'test@example.com'}]);
  $user->untag('test tag');

  # Change the user's name
  $user->name = 'new name';
  $user->save();

  # Delete the user
  $user->delete();
  $intercom->user_delete(email => 'test@example.com');

  # Add a note
  $user->add_note(body => "This is a test note");
  $intercom->note_create(email => 'test@example.com',
                         body => "This is a test note");
 
  # Add an event
  $user->add_event(event_name => 'test event');
  $intercom->event_create(email => 'test@example.com',
                          event_name => 'test event',
                          metadata => {
                             "article" =>  {"url" =>  "https://example.org/",
                                            "value" => "link text"},
                          });

DESCRIPTION

Provides a nice API for Intercom.io rather than making raw requests.

IMPLEMENTATION PHILOSOPHY

This module attempts to stick as close to the API as possible.

Documentation for the v2 API:

http://doc.intercom.io/api/

For examples see the test cases, most functionality is well exercised via tests.

FUNCTIONS

user_get

Retrieves an existing user.

  $intercom->user_get(Maybe[Str] :$user_id?,
                      Maybe[Str] :$email?,
                      Maybe[Str] :$id?);

Only one of user_id, email or id are required to retrieve a user.

Returns a WebService::Intercom::User.

user_create_or_update

Creates or updates a user.

  # When you have an existing WebService::Intercom::User
  $intercom->user_create_or_update(WebService::Intercom::User $user);

  or

  $intercom->user_create_or_update(Maybe[Str] :$user_id?,
                                   Maybe[Str] :$email?,
                                   Maybe[Str] :$id?,
                                   Maybe[Int] :$signed_up_at?,
                                   Str :$name?,
                                   Maybe[IPAddressType] :$last_seen_ip?,
                                   CustomAttributesType :$custom_attributes?,
                                   Maybe[Str] :$last_seen_user_agent?,
                                   HashRef :$companies?,
                                   Maybe[Int] :$last_request_at?,
                                   Maybe[Bool] :$unsubscribed_from_emails?,
                                   Maybe[Bool] :$update_last_request_at?,
                                   Maybe[Bool] :$new_session?);
  

Returns a WebService::Intercom::User that represents the new or updated user.

user_delete

Deletes a user

  # When you have an existing WebService::Intercom::User
  $intercom->user_delete(WebService::Intercom::User $user);

  or

  $intercom->user_delete(Maybe[Str] :$user_id?,
                         Maybe[Str] :$email?,
                         Maybe[Str] :$id?);

Only one of user_id, email or id is required.

Returns a WebService::Intercom::User that represents the deleted user.

tag_create_or_update

Creates or updates a tag.

  # When you have an existing WebService::Intercom::User
  $intercom->tag_create_or_update(WebService::Intercom::Tag $tag);

  or

  $intercom->tag_create_or_update(Str :$name,
                                  Maybe[Str] :$id?);

Returns a WebService::Intercom::Tag that represents the tag.

tag_items

Applies or removes a tag to users or companies

  # When you have an existing WebService::Intercom::User
  $intercom->tag_items(Str :$name,
                       ArrayRef[TagUserIdentifierType] :$users?,
                       ArrayRef[TagCompanyIdentifierType] :$companies?);

tag_delete

Deletes a tag

  # When you have an existing WebService::Intercom::User
  $intercom->tag_delete(WebService::Intercom::Tag $tag);

  or

  $intercom->tag_delete(Str :$id);

Returns undef

note_create

Creates a note for a user

  # When you have an existing WebService::Intercom::User
  $intercom->note_create(Maybe[Str] :$user_id?,
                         Maybe[Str] :$email?,
                         Maybe[Str] :$id?,
                         Maybe[Str] :$admin_id?,
                         Str :$body);

Returns a WebService::Intercom::Note that represents the note.

event_create

Creates an event for a user

  # When you have an existing WebService::Intercom::User
  $intercom->event_create(Maybe[Str] :$user_id?,
                          Maybe[Str] :$email?,
                          EventNameType :$event_name,
                          Maybe[Int] :$created_at?,
                          Maybe[EventMetadataType] :$metadata?);

Returns undef.

create_message

Create a message, can be user or admin initiated.

  # When you have an existing WebService::Intercom::User
  $intercom->create_message(MessagePersonType :$from,
                          Maybe[MessagePersonType] :$to,
                          Str :$body,
                          Maybe[Str] :$subject?,
                          Maybe[StrMatch[qr/^(plain|personal)$/]] :$template,
                          StrMatch[qr/^(inapp|email)$/] :$message_type);

Returns a WebService::Intercom::Message.

SEE ALSO

See Moops and Kavorka to understand parameter signatures.

Also of course Intercom at http://www.intercom.io.

AUTHOR

Rusty Conover <rusty+cpan@luckydinosaur.com>

COPYRIGHT

This software is copyright (c) 2015 by Lucky Dinosaur LLC. http://www.luckydinosaur.com

This is free software; you can redistribute it and/or modify it under the same terms as the Perl 5 programming language system itself.

DISCLAIMER OF WARRANTIES

THIS PACKAGE IS PROVIDED "AS IS" AND WITHOUT ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, WITHOUT LIMITATION, THE IMPLIED WARRANTIES OF MERCHANTIBILITY AND FITNESS FOR A PARTICULAR PURPOSE.

cpanm WebService::Intercom

perl -MCPAN -e shell
install WebService::Intercom