helpscout 0.1.3

连接

连接到HelpScout API需要API密钥，该密钥是在您的HelpScout账户中生成的。在下面的示例中，我们的密钥是API_KEY。

from helpscout import HelpScout
hs = HelpScout('API_KEY')

API端点

HelpScout API端点作为实例化的HelpScout对象上的变量暴露。可用的端点包括

• 对话端点

• 客户端点

• 邮箱端点

• 标签端点

• 团队端点

• 用户端点

• WebHook端点

它们也可以从HelpScout的__apis__属性中查看

>>> hs.__apis__
{'Conversations': <helpscout.auth_proxy.AuthProxy object at 0x10783ddd0>,
 'Customers': <helpscout.auth_proxy.AuthProxy object at 0x10783dd90>,
 'Mailboxes': <helpscout.auth_proxy.AuthProxy object at 0x10783ded0>,
 'Users': <helpscout.auth_proxy.AuthProxy object at 0x10783df50>,
 'Teams': <helpscout.auth_proxy.AuthProxy object at 0x10783df10>,
 }

API使用非常简单，只需调用带有所需参数的方法并迭代结果即可

for customer in hs.Customers.list(first_name='Help', last_name='Scout'):
    print(customer)
    print(customer.serialize())

当使用HelpScout演示数据时，上述输出的结果可能如下所示

# This is the customer object itself (first print)
<helpscout.models.customer.Customer object at 0x10783df10>
# This is the serialized form of the customer (second print)
{'chats': [],
 'social_profiles': [],
 'first_name': u'Help',
 'last_name': u'Scout',
 'phones': [],
 'created_at': '2017-09-16T18:38:37Z',
 'modified_at': '2017-09-16T18:38:37Z',
 u'__class__': 'Customer',
 'websites': [],
 'id': 143161083,
 'location': u'Boston, MA',
 'full_name': u'Help Scout',
 'gender': 'unknown',
 'photo_type': 'gravatar',
 'type': 'customer',
 'emails': [],
 'photo_url': u'https://secure.gravatar.com/avatar/7d599977ec288a9141317b352c04d497'}

在某些情况下，例如通过ID浏览记录时，预期会出现单例。在这些情况下，直接使用单例而不是迭代。

>>> customer = hs.Customers.get(143161083)
>>> customer
<helpscout.models.customer.Customer object at 0x101723e50>
>>> from pprint import pprint
>>> pprint(customer.serialize())
{u'__class__': 'Customer',
 'address': {u'__class__': 'Address',
             'city': u'Boston',
             'country': u'US',
             'created_at': '2017-09-16T18:38:37Z',
             'id': 4996350,
             'lines': [u'131 Tremont Street', u'3rd Floor'],
             'postal_code': u'02111-1338',
             'state': u'MA'},
 'chats': [],
 'created_at': '2017-09-16T18:38:37Z',
 'emails': [{u'__class__': 'Email',
             'id': 189240662,
             'location': 'work',
             'value': u'help@helpscout.net'}],
 'first_name': u'Help',
 'full_name': u'Help Scout',
 'gender': 'unknown',
 'id': 143161083,
 'last_name': u'Scout',
 'location': u'Boston, MA',
 'modified_at': '2017-09-16T18:38:37Z',
 'phones': [{u'__class__': 'Phone',
             'id': 189240668,
             'location': 'work',
             'value': u'855-435-7726'}],
 'photo_type': 'gravatar',
 'photo_url': u'https://secure.gravatar.com/avatar/7d599977ec288a9141317b352c04d497',
 'social_profiles': [{u'__class__': 'SocialProfile',
                      'id': 189240667,
                      'type': 'twitter',
                      'value': u'http://twitter.com/helpscout'},
                     {u'__class__': 'SocialProfile',
                      'id': 189240663,
                      'type': 'twitter',
                      'value': u'https://twitter.com/helpscout'},
                     {u'__class__': 'SocialProfile',
                      'id': 189240664,
                      'type': 'twitter',
                      'value': u'https://twitter.com/HelpScoutDev'}],
 'type': 'customer',
 'websites': [{u'__class__': 'Website',
               'id': 189240670,
               'value': u'http://developer.helpscout.net'},
              {u'__class__': 'Website',
               'id': 189240665,
               'value': u'http://status.helpscout.net/'},
              {u'__class__': 'Website',
               'id': 189240666,
               'value': u'http://www.helpscout.com'},
              {u'__class__': 'Website',
               'id': 189240671,
               'value': u'http://www.helpscout.net'}]}

请注意，所有API响应都将被解析，并从结果中创建合适的对象。这些对象都定义在helpscout.models包中。

搜索

以下端点实现了.search()方法

• 会话搜索

• 客户搜索

搜索接受实例化的Domain或查询迭代器

[('subject', 'Test1'),
 'OR',
 ('subject', 'Test2')',
 ('subject', 'Test3')',
 ]

上述内容等同于以下HelpScout查询字符串

(subject:'Test1' OR subject:'Test2' OR subject:'Test3')

以下是一个使用示例

>>> res = hs.Conversations.search([('subject', 'Learning')])
>>> for r in res:
>>>     r.serialize()
{'status': 'active', 'customer_email': u'help@helpscout.net', 'thread_count': 0, 'modified_at': '2017-09-16T18:38:37Z', 'number': 150, 'subject': u'Learning the basics', u'__class__': 'SearchConversation', 'has_attachments': False, 'mailbox_id': 122867, 'preview': u'Hey Dave, Above this message is what we call the Conversation Toolbar. From there you can take all sorts of actions on a Conversation. Hover your mouse over each of the icons to see what you can do....', 'id': 432907900, 'customer_name': u'Help Scout'}

Web Hooks

Web Hooks可以通过使用在HelpScout账户中设置钩子时配置的秘密密钥实例化HelpScoutWebHook来接收

from helpscout import HelpScoutWebHook

hook = HelpScoutWebHook('your secret key')

为了实际接收请求，请调用实例化后的HelpScoutWebHook上的receive方法

signature = '2iFmnzC8SCNVF/iNiMnSe19yceU=\n'  # (``X-HelpScout-Signature`` Header)
event_type = 'customer.created'  # (``X-HelpScout-Event`` Header)
request_body = '{"firstName":"Jackie","lastName":"Chan",' \
               '"email":"jackie.chan@somewhere.com",' \
               '"gender":"male"}'

event = web_hook.receive(
    event_type, signature, request_body,
)

返回的WebHookEvent包含两个属性

• event_type (str)：表示事件类型

• record (helpscout.BaseModel)：此请求的解析数据记录

根据上述示例

>>> event.event_type
'customer.created'
>>> event.record
<helpscout.models.customer.Customer object at 0x101723e50>

您使用标准端点创建创建一个web hook

from helpscout.models import HelpScoutWebHook
hook = HelpScoutWebHook(
   url='https://example.com/my/web/hook/'
   secret_key='SuperSecretRandomizedString'
   events=[
      'customer.created',
   ],
)
hs.WebHook.create(hook)

上述示例将使用上述示例中的预认证的HelpScout对象（hs）为customer.created事件创建一个钩子。

贡献者

• Dave Lasley <dave@laslabs.com>

• Brent Hughes <brent.hughes@laslabs.com>

维护者

此模块由LasLabs Inc.维护