Class: MessageBird::Client

Inherits:
Object
  • Object
show all
Defined in:
lib/messagebird/client.rb

Instance Attribute Summary collapse

Instance Method Summary collapse

Constructor Details

#initialize(access_key = nil, http_client = nil, conversation_client = nil, voice_client = nil) ⇒ Client

Returns a new instance of Client.



50
51
52
53
54
55
56
 
# File 'lib/messagebird/client.rb', line 50

def initialize(access_key = nil, http_client = nil, conversation_client = nil, voice_client = nil)
  @access_key = access_key || ENV['MESSAGEBIRD_ACCESS_KEY']
  @http_client = http_client || HttpClient.new(@access_key)
  @conversation_client = conversation_client || ConversationClient.new(@access_key)
  @number_client = http_client || NumberClient.new(@access_key)
  @voice_client = voice_client || VoiceClient.new(@access_key)
end

Instance Attribute Details

#access_key ⇒ Object (readonly)

Returns the value of attribute access_key.



48
49
50
 
# File 'lib/messagebird/client.rb', line 48

def access_key
  @access_key
end

#conversation_client ⇒ Object (readonly)

Returns the value of attribute conversation_client.



48
49
50
 
# File 'lib/messagebird/client.rb', line 48

def conversation_client
  @conversation_client
end

#http_client ⇒ Object (readonly)

Returns the value of attribute http_client.



48
49
50
 
# File 'lib/messagebird/client.rb', line 48

def http_client
  @http_client
end

#voice_client ⇒ Object (readonly)

Returns the value of attribute voice_client.



48
49
50
 
# File 'lib/messagebird/client.rb', line 48

def voice_client
  @voice_client
end

Instance Method Details

#balance ⇒ Object

Retrieve your balance.



187
188
189
 
# File 'lib/messagebird/client.rb', line 187

def balance
  Balance.new(request(:get, 'balance'))
end

#call_create(source, destination, call_flow = {}, webhook = {}, params = {}) ⇒ Object 



299
300
301
302
303
304
 
# File 'lib/messagebird/client.rb', line 299

def call_create(source, destination, call_flow = {}, webhook = {}, params = {})
  params = params.merge(callFlow: call_flow.to_json) unless call_flow.empty?
  params = params.merge(webhook: webhook.to_json) unless webhook.empty?

  Voice::Call.new(voice_request(:post, 'calls', params.merge(source: source, destination: destination)))
end

#call_delete(id) ⇒ Object 



314
315
316
 
# File 'lib/messagebird/client.rb', line 314

def call_delete(id)
  voice_request(:delete, "calls/#{id}")
end

#call_flow_create(title, steps, default, record, params = {}) ⇒ Object 



460
461
462
463
464
465
466
467
468
 
# File 'lib/messagebird/client.rb', line 460

def call_flow_create(title, steps, default, record, params = {})
  params = params.merge(
    title: title,
    steps: steps,
    default: default,
    record: record
  )
  CallFlow.new(voice_request(:post, 'call-flows', params))
end

#call_flow_delete(id) ⇒ Object 



478
479
480
 
# File 'lib/messagebird/client.rb', line 478

def call_flow_delete(id)
  voice_request(:delete, "call-flows/#{id}")
end

#call_flow_list(per_page = CallFlowList::PER_PAGE, page = CallFlowList::CURRENT_PAGE) ⇒ Object 



474
475
476
 
# File 'lib/messagebird/client.rb', line 474

def call_flow_list(per_page = CallFlowList::PER_PAGE, page = CallFlowList::CURRENT_PAGE)
  CallFlowList.new(CallFlow, voice_request(:get, "call-flows?perPage=#{per_page}&page=#{page}"))
end

#call_flow_view(id) ⇒ Object 



470
471
472
 
# File 'lib/messagebird/client.rb', line 470

def call_flow_view(id)
  CallFlow.new(voice_request(:get, "call-flows/#{id}"))
end

#call_leg_list(call_id, per_page = Voice::List::PER_PAGE, current_page = Voice::List::CURRENT_PAGE) ⇒ Object 



318
319
320
 
# File 'lib/messagebird/client.rb', line 318

def call_leg_list(call_id, per_page = Voice::List::PER_PAGE, current_page = Voice::List::CURRENT_PAGE)
  Voice::List.new(Voice::CallLeg, voice_request(:get, "calls/#{call_id}/legs?perPage=#{per_page}&currentPage=#{current_page}"))
end

#call_leg_recording_delete(call_id, leg_id, recording_id) ⇒ Object 



330
331
332
 
# File 'lib/messagebird/client.rb', line 330

def call_leg_recording_delete(call_id, leg_id, recording_id)
  voice_request(:delete, "calls/#{call_id}/legs/#{leg_id}/recordings/#{recording_id}")
end

#call_leg_recording_download(recording_uri, &block) ⇒ Object 



334
335
336
 
# File 'lib/messagebird/client.rb', line 334

def call_leg_recording_download(recording_uri, &block)
  @voice_client.request_block(:get, recording_uri, {}, &block)
end

#call_leg_recording_list(call_id, leg_id) ⇒ Object 



326
327
328
 
# File 'lib/messagebird/client.rb', line 326

def call_leg_recording_list(call_id, leg_id)
  Voice::List.new(Voice::CallLegRecording, voice_request(:get, "calls/#{call_id}/legs/#{leg_id}/recordings"))
end

#call_leg_recording_view(call_id, leg_id, recording_id) ⇒ Object 



322
323
324
 
# File 'lib/messagebird/client.rb', line 322

def call_leg_recording_view(call_id, leg_id, recording_id)
  Voice::CallLegRecording.new(voice_request(:get, "calls/#{call_id}/legs/#{leg_id}/recordings/#{recording_id}"))
end

#call_list(per_page = Voice::List::PER_PAGE, page = Voice::List::CURRENT_PAGE) ⇒ Object 



306
307
308
 
# File 'lib/messagebird/client.rb', line 306

def call_list(per_page = Voice::List::PER_PAGE, page = Voice::List::CURRENT_PAGE)
  Voice::List.new(Voice::Call, voice_request(:get, "calls?perPage=#{per_page}&currentPage=#{page}"))
end

#call_view(id) ⇒ Object 



310
311
312
 
# File 'lib/messagebird/client.rb', line 310

def call_view(id)
  Voice::Call.new(voice_request(:get, "calls/#{id}"))
end

#contact(id) ⇒ Object 



374
375
376
 
# File 'lib/messagebird/client.rb', line 374

def contact(id)
  Contact.new(request(:get, "contacts/#{id}"))
end

#contact_create(phone_number, params = {}) ⇒ Object 



366
367
368
369
370
371
372
 
# File 'lib/messagebird/client.rb', line 366

def contact_create(phone_number, params = {})
  Contact.new(request(
                :post,
                'contacts',
                params.merge(msisdn: phone_number.to_s)
  ))
end

#contact_delete(id) ⇒ Object 



378
379
380
 
# File 'lib/messagebird/client.rb', line 378

def contact_delete(id)
  request(:delete, "contacts/#{id}")
end

#contact_list(limit = 0, offset = 0) ⇒ Object 



386
387
388
 
# File 'lib/messagebird/client.rb', line 386

def contact_list(limit = 0, offset = 0)
  List.new(Contact, request(:get, "contacts?limit=#{limit}&offset=#{offset}"))
end

#contact_update(id, params = {}) ⇒ Object 



382
383
384
 
# File 'lib/messagebird/client.rb', line 382

def contact_update(id, params = {})
  request(:patch, "contacts/#{id}", params)
end

#conversation(id) ⇒ Object 



131
132
133
 
# File 'lib/messagebird/client.rb', line 131

def conversation(id)
  Conversation.new(conversation_request(:get, "conversations/#{id}"))
end

#conversation_list(limit = -1,, offset = -1)) ⇒ Object 



118
119
120
121
122
123
124
125
126
127
128
129
 
# File 'lib/messagebird/client.rb', line 118

def conversation_list(limit = -1, offset = -1)
  query = '?'
  if limit != -1
    query += "limit=#{limit}&"
  end

  if offset != -1
    query += "offset=#{offset}"
  end

  List.new(Conversation, conversation_request(:get, "conversations#{query}"))
end

#conversation_message(id) ⇒ Object 



156
157
158
 
# File 'lib/messagebird/client.rb', line 156

def conversation_message(id)
  ConversationMessage.new(conversation_request(:get, "messages/#{id}"))
end

#conversation_messages_list(id, limit = -1,, offset = -1)) ⇒ Object 



143
144
145
146
147
148
149
150
151
152
153
154
 
# File 'lib/messagebird/client.rb', line 143

def conversation_messages_list(id, limit = -1, offset = -1)
  query = '?'
  if limit != -1
    query += "limit=#{limit}&"
  end

  if offset != -1
    query += "offset=#{offset}"
  end

  List.new(ConversationMessage, conversation_request(:get, "conversations/#{id}/messages#{query}"))
end

#conversation_reply(id, params = {}) ⇒ Object 



139
140
141
 
# File 'lib/messagebird/client.rb', line 139

def conversation_reply(id, params = {})
  ConversationMessage.new(conversation_request(:post, "conversations/#{id}/messages", params))
end

#conversation_request(method, path, params = {}) ⇒ Object 



58
59
60
61
62
63
 
# File 'lib/messagebird/client.rb', line 58

def conversation_request(method, path, params = {})
  response_body = @conversation_client.request(method, path, params)
  return if response_body.nil? || response_body.empty?

  parse_body(response_body)
end

#conversation_update(id, status) ⇒ Object 



135
136
137
 
# File 'lib/messagebird/client.rb', line 135

def conversation_update(id, status)
  Conversation.new(conversation_request(:patch, "conversations/#{id}", status: status))
end

#conversation_webhook(id) ⇒ Object 



178
179
180
 
# File 'lib/messagebird/client.rb', line 178

def conversation_webhook(id)
  ConversationWebhook.new(conversation_request(:get, "webhooks/#{id}"))
end

#conversation_webhook_create(channel_id, url, events = []) ⇒ Object 



160
161
162
163
164
165
166
167
168
 
# File 'lib/messagebird/client.rb', line 160

def conversation_webhook_create(channel_id, url, events = [])
  ConversationWebhook.new(conversation_request(
                            :post,
                            'webhooks',
                            channel_id: channel_id,
                            url: url,
                            events: events
  ))
end

#conversation_webhook_delete(id) ⇒ Object 



182
183
184
 
# File 'lib/messagebird/client.rb', line 182

def conversation_webhook_delete(id)
  conversation_request(:delete, "webhooks/#{id}")
end

#conversation_webhook_update(id, params = {}) ⇒ Object 



174
175
176
 
# File 'lib/messagebird/client.rb', line 174

def conversation_webhook_update(id, params = {})
  ConversationWebhook.new(conversation_request(:patch, "webhooks/#{id}", params))
end

#conversation_webhooks_list(limit = 0, offset = 0) ⇒ Object 



170
171
172
 
# File 'lib/messagebird/client.rb', line 170

def conversation_webhooks_list(limit = 0, offset = 0)
  List.new(ConversationWebhook, conversation_request(:get, "webhooks?limit=#{limit}&offset=#{offset}"))
end

#group(id) ⇒ Object 



390
391
392
 
# File 'lib/messagebird/client.rb', line 390

def group(id)
  Group.new(request(:get, "groups/#{id}"))
end

#group_add_contacts(group_id, contact_ids) ⇒ Object 



410
411
412
413
414
415
416
417
 
# File 'lib/messagebird/client.rb', line 410

def group_add_contacts(group_id, contact_ids)
  # We expect an array, but we can handle a string ID as well...
  contact_ids = [contact_ids] if contact_ids.is_a? String

  query = add_contacts_query(contact_ids)

  request(:get, "groups/#{group_id}?#{query}")
end

#group_create(name) ⇒ Object 



394
395
396
 
# File 'lib/messagebird/client.rb', line 394

def group_create(name)
  Group.new(request(:post, 'groups', name: name))
end

#group_delete(id) ⇒ Object 



398
399
400
 
# File 'lib/messagebird/client.rb', line 398

def group_delete(id)
  request(:delete, "groups/#{id}")
end

#group_delete_contact(group_id, contact_id) ⇒ Object 



419
420
421
 
# File 'lib/messagebird/client.rb', line 419

def group_delete_contact(group_id, contact_id)
  request(:delete, "groups/#{group_id}/contacts/#{contact_id}")
end

#group_list(limit = 0, offset = 0) ⇒ Object 



402
403
404
 
# File 'lib/messagebird/client.rb', line 402

def group_list(limit = 0, offset = 0)
  List.new(Group, request(:get, "groups?limit=#{limit}&offset=#{offset}"))
end

#group_update(id, name) ⇒ Object 



406
407
408
 
# File 'lib/messagebird/client.rb', line 406

def group_update(id, name)
  request(:patch, "groups/#{id}", name: name)
end

#hlr(id) ⇒ Object

Retrieve the information of specific HLR.



192
193
194
 
# File 'lib/messagebird/client.rb', line 192

def hlr(id)
  HLR.new(request(:get, "hlr/#{id}"))
end

#hlr_create(msisdn, reference) ⇒ Object

Create a new HLR.



197
198
199
200
201
202
203
204
 
# File 'lib/messagebird/client.rb', line 197

def hlr_create(msisdn, reference)
  HLR.new(request(
            :post,
            'hlr',
            msisdn: msisdn,
            reference: reference
  ))
end

#lookup(phone_number, params = {}) ⇒ Object 



354
355
356
 
# File 'lib/messagebird/client.rb', line 354

def lookup(phone_number, params = {})
  Lookup.new(request(:get, "lookup/#{phone_number}", params))
end

#lookup_hlr(phone_number, params = {}) ⇒ Object 



362
363
364
 
# File 'lib/messagebird/client.rb', line 362

def lookup_hlr(phone_number, params = {})
  HLR.new(request(:get, "lookup/#{phone_number}/hlr", params))
end

#lookup_hlr_create(phone_number, params = {}) ⇒ Object 



358
359
360
 
# File 'lib/messagebird/client.rb', line 358

def lookup_hlr_create(phone_number, params = {})
  HLR.new(request(:post, "lookup/#{phone_number}/hlr", params))
end

#message(id) ⇒ Object

Retrieve the information of specific message.



236
237
238
 
# File 'lib/messagebird/client.rb', line 236

def message(id)
  Message.new(request(:get, "messages/#{id}"))
end

#message_create(originator, recipients, body, params = {}) ⇒ Object

Create a new message.



249
250
251
252
253
254
255
256
257
258
259
260
 
# File 'lib/messagebird/client.rb', line 249

def message_create(originator, recipients, body, params = {})
  # Convert an array of recipients to a comma-separated string.
  recipients = recipients.join(',') if recipients.is_a?(Array)

  Message.new(request(
                :post,
                'messages',
                params.merge(originator: originator.to_s,
                             body: body.to_s,
                             recipients: recipients)
  ))
end

#message_list(filters = {}) ⇒ Object

Retrieve messages with optional paging and status filter.



241
242
243
244
245
246
 
# File 'lib/messagebird/client.rb', line 241

def message_list(filters = {})
  params = { limit: 10, offset: 0 }.merge(filters).compact
  query = "messages?#{URI.encode_www_form(params)}"

  List.new(Message, request(:get, query))
end

#number_cancel(number) ⇒ Object

Cancel a number



456
457
458
 
# File 'lib/messagebird/client.rb', line 456

def number_cancel(number)
  number_request(:delete, "phone-numbers/#{number}")
end

#number_fetch(number) ⇒ Object

Fetch specific purchased number’s details



445
446
447
 
# File 'lib/messagebird/client.rb', line 445

def number_fetch(number)
  Number.new(number_request(:get, "phone-numbers/#{number}"))
end

#number_fetch_all(params = {}) ⇒ Object

Fetch all purchaed numbers’ details



440
441
442
 
# File 'lib/messagebird/client.rb', line 440

def number_fetch_all(params = {})
  List.new(Number, number_request(:get, add_querystring('phone-numbers', params), params))
end

#number_purchase(number, country_code, billing_interval_months) ⇒ Object

Purchase an avaiable number



430
431
432
433
434
435
436
437
 
# File 'lib/messagebird/client.rb', line 430

def number_purchase(number, country_code, billing_interval_months)
  params = {
    number: number,
    countryCode: country_code,
    billingIntervalMonths: billing_interval_months
  }
  Number.new(number_request(:post, 'phone-numbers', params))
end

#number_request(method, path, params = {}) ⇒ Object 



65
66
67
68
69
70
 
# File 'lib/messagebird/client.rb', line 65

def number_request(method, path, params = {})
  response_body = @number_client.request(method, path, params)
  return if response_body.nil? || response_body.empty?

  parse_body(response_body)
end

#number_search(country_code, params = {}) ⇒ Object

Numbers API Search for available numbers



425
426
427
 
# File 'lib/messagebird/client.rb', line 425

def number_search(country_code, params = {})
  List.new(Number, number_request(:get, add_querystring("available-phone-numbers/#{country_code}", params), params))
end

#number_update(number, tags) ⇒ Object

Update a number



450
451
452
453
 
# File 'lib/messagebird/client.rb', line 450

def number_update(number, tags)
  tags = [tags] if tags.is_a? String
  Number.new(number_request(:patch, "phone-numbers/#{number}", tags: tags))
end

#parse_body(body) ⇒ Object 



86
87
88
89
90
91
92
93
94
95
 
# File 'lib/messagebird/client.rb', line 86

def parse_body(body)
  json = JSON.parse(body)

  # If the request returned errors, create Error objects and raise.
  if json.key?('errors')
    raise(ErrorException, json['errors'].map { |e| Error.new(e) })
  end

  json
end

#request(method, path, params = {}) ⇒ Object 



79
80
81
82
83
84
 
# File 'lib/messagebird/client.rb', line 79

def request(method, path, params = {})
  response_body = @http_client.request(method, path, params)
  return if response_body.nil? || response_body.empty?

  parse_body(response_body)
end

#send_conversation_message(from, to, params = {}) ⇒ Object

Conversations Send a conversation message



99
100
101
102
103
104
105
106
 
# File 'lib/messagebird/client.rb', line 99

def send_conversation_message(from, to, params = {})
  ConversationMessage.new(conversation_request(
                            :post,
                            'send',
                            params.merge(from: from,
                                         to: to)
  ))
end

#start_conversation(to, channel_id, params = {}) ⇒ Object

Start a conversation



109
110
111
112
113
114
115
116
 
# File 'lib/messagebird/client.rb', line 109

def start_conversation(to, channel_id, params = {})
  Conversation.new(conversation_request(
                     :post,
                     'conversations/start',
                     params.merge(to: to,
                                  channel_id: channel_id)
  ))
end

#verify(id) ⇒ Object

Retrieve the information of specific Verify.



207
208
209
 
# File 'lib/messagebird/client.rb', line 207

def verify(id)
  Verify.new(request(:get, "verify/#{id}"))
end

#verify_create(recipient, params = {}) ⇒ Object

Generate a new One-Time-Password message.



217
218
219
220
221
222
223
 
# File 'lib/messagebird/client.rb', line 217

def verify_create(recipient, params = {})
  Verify.new(request(
               :post,
               'verify',
               params.merge(recipient: recipient)
  ))
end

#verify_delete(id) ⇒ Object

Delete a Verify, response is empty



231
232
233
 
# File 'lib/messagebird/client.rb', line 231

def verify_delete(id)
  request(:delete, "verify/#{id}")
end

#verify_email_message(id) ⇒ Object

Retrieve the information of specific Verify email message



212
213
214
 
# File 'lib/messagebird/client.rb', line 212

def verify_email_message(id)
  VerifyEmailMessage.new(request(:get, "verify/messages/email/#{id}"))
end

#verify_token(id, token) ⇒ Object

Verify the One-Time-Password.



226
227
228
 
# File 'lib/messagebird/client.rb', line 226

def verify_token(id, token)
  Verify.new(request(:get, "verify/#{id}?token=#{token}"))
end

#voice_message(id) ⇒ Object

Retrieve the information of a specific voice message.



263
264
265
 
# File 'lib/messagebird/client.rb', line 263

def voice_message(id)
  VoiceMessage.new(request(:get, "voicemessages/#{id}"))
end

#voice_message_create(recipients, body, params = {}) ⇒ Object

Create a new voice message.



268
269
270
271
272
273
274
275
276
277
 
# File 'lib/messagebird/client.rb', line 268

def voice_message_create(recipients, body, params = {})
  # Convert an array of recipients to a comma-separated string.
  recipients = recipients.join(',') if recipients.is_a?(Array)

  VoiceMessage.new(request(
                     :post,
                     'voicemessages',
                     params.merge(recipients: recipients, body: body.to_s)
  ))
end

#voice_request(method, path, params = {}) ⇒ Object 



72
73
74
75
76
77
 
# File 'lib/messagebird/client.rb', line 72

def voice_request(method, path, params = {})
  response_body = @voice_client.request(method, path, params)
  return if response_body.nil? || response_body.empty?

  parse_body(response_body)
end

#voice_transcription_create(call_id, leg_id, recording_id, params = {}) ⇒ Object 



338
339
340
 
# File 'lib/messagebird/client.rb', line 338

def voice_transcription_create(call_id, leg_id, recording_id, params = {})
  Voice::Transcription.new(voice_request(:post, "calls/#{call_id}/legs/#{leg_id}/recordings/#{recording_id}/transcriptions", params))
end

#voice_transcription_download(call_id, leg_id, recording_id, transcription_id, &block) ⇒ Object 



346
347
348
 
# File 'lib/messagebird/client.rb', line 346

def voice_transcription_download(call_id, leg_id, recording_id, transcription_id, &block)
  @voice_client.request_block(:get, "calls/#{call_id}/legs/#{leg_id}/recordings/#{recording_id}/transcriptions/#{transcription_id}.txt", {}, &block)
end

#voice_transcription_view(call_id, leg_id, recording_id, transcription_id) ⇒ Object 



350
351
352
 
# File 'lib/messagebird/client.rb', line 350

def voice_transcription_view(call_id, leg_id, recording_id, transcription_id)
  Voice::Transcription.new(voice_request(:get, "calls/#{call_id}/legs/#{leg_id}/recordings/#{recording_id}/transcriptions/#{transcription_id}"))
end

#voice_transcriptions_list(call_id, leg_id, recording_id) ⇒ Object 



342
343
344
 
# File 'lib/messagebird/client.rb', line 342

def voice_transcriptions_list(call_id, leg_id, recording_id)
  Voice::List.new(Voice::Transcription, voice_request(:get, "calls/#{call_id}/legs/#{leg_id}/recordings/#{recording_id}/transcriptions"))
end

#voice_webhook(id) ⇒ Object 



291
292
293
 
# File 'lib/messagebird/client.rb', line 291

def voice_webhook(id)
  Voice::Webhook.new(voice_request(:get, "webhooks/#{id}"))
end

#voice_webhook_create(url, params = {}) ⇒ Object 



279
280
281
 
# File 'lib/messagebird/client.rb', line 279

def voice_webhook_create(url, params = {})
  Voice::Webhook.new(voice_request(:post, 'webhooks', params.merge(url: url)))
end

#voice_webhook_delete(id) ⇒ Object 



295
296
297
 
# File 'lib/messagebird/client.rb', line 295

def voice_webhook_delete(id)
  voice_request(:delete, "webhooks/#{id}")
end

#voice_webhook_update(id, params = {}) ⇒ Object 



287
288
289
 
# File 'lib/messagebird/client.rb', line 287

def voice_webhook_update(id, params = {})
  Voice::Webhook.new(voice_request(:put, "webhooks/#{id}", params))
end

#voice_webhooks_list(per_page = VoiceList::PER_PAGE, page = VoiceList::CURRENT_PAGE) ⇒ Object 



283
284
285
 
# File 'lib/messagebird/client.rb', line 283

def voice_webhooks_list(per_page = VoiceList::PER_PAGE, page = VoiceList::CURRENT_PAGE)
  Voice::List.new(Voice::Webhook, voice_request(:get, "webhooks?perPage=#{per_page}&page=#{page}"))
end