sendly 4.5.1 → 4.7.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- checksums.yaml +4 -4
- data/CHANGELOG.md +20 -0
- data/Gemfile.lock +1 -1
- data/README.md +182 -38
- data/lib/sendly/calls_resource.rb +122 -12
- data/lib/sendly/client.rb +11 -0
- data/lib/sendly/conversations_resource.rb +12 -4
- data/lib/sendly/enterprise.rb +62 -11
- data/lib/sendly/messages.rb +7 -1
- data/lib/sendly/rules_resource.rb +2 -1
- data/lib/sendly/short_codes_resource.rb +336 -0
- data/lib/sendly/templates_resource.rb +21 -0
- data/lib/sendly/types.rb +155 -4
- data/lib/sendly/version.rb +1 -1
- data/lib/sendly/voice_resource.rb +314 -17
- data/lib/sendly/webhooks_resource.rb +20 -0
- data/lib/sendly/whatsapp_resource.rb +20 -7
- data/lib/sendly.rb +1 -0
- metadata +3 -2
|
@@ -125,11 +125,10 @@ module Sendly
|
|
|
125
125
|
# What an agent may do on a call.
|
|
126
126
|
#
|
|
127
127
|
# +send_sms+ is true when the agent may text the caller; it confirms the
|
|
128
|
-
# number back to them before sending. +transfer_to+ is
|
|
129
|
-
#
|
|
130
|
-
#
|
|
131
|
-
#
|
|
132
|
-
# agent takes their name and number.
|
|
128
|
+
# number back to them before sending. +transfer_to+ is the E.164 number
|
|
129
|
+
# the agent transfers a caller to when asked for a person, and the one
|
|
130
|
+
# {CallsResource#transfer} uses when given no number; +nil+ when the agent
|
|
131
|
+
# cannot transfer.
|
|
133
132
|
class VoiceAgentTools
|
|
134
133
|
attr_reader :send_sms, :transfer_to
|
|
135
134
|
|
|
@@ -148,6 +147,66 @@ module Sendly
|
|
|
148
147
|
end
|
|
149
148
|
end
|
|
150
149
|
|
|
150
|
+
# How Sendly reaches your own agent, as {VoiceAgent#connection} reports
|
|
151
|
+
# it. Which readers are set follows the agent's +kind+; the rest are +nil+.
|
|
152
|
+
#
|
|
153
|
+
# "custom_llm": +base_url+ (Sendly sends +POST {base_url}/chat/completions+
|
|
154
|
+
# with streaming on), +model+, +header_names+ (the names of the extra
|
|
155
|
+
# headers sent) and +has_api_key+.
|
|
156
|
+
#
|
|
157
|
+
# "sip": +uri+ (such as "sip:+15125550100@sip.example.com"), +transport+
|
|
158
|
+
# (one of {SIP_TRANSPORTS}), +media_encryption+ (one of
|
|
159
|
+
# {SIP_MEDIA_ENCRYPTION}), +username+ (or +nil+), +has_password+ and
|
|
160
|
+
# +headers+ (the extra X- headers sent on the call).
|
|
161
|
+
#
|
|
162
|
+
# "websocket": +url+ (your wss:// server), +audio_format+ (one of
|
|
163
|
+
# {WEBSOCKET_AUDIO_FORMATS}), +has_auth_token+ and +custom_parameters+
|
|
164
|
+
# (sent to your server in the +start+ message).
|
|
165
|
+
#
|
|
166
|
+
# Secrets (the API key, the custom_llm header values, the SIP password and
|
|
167
|
+
# the auth token) are never returned, only whether one is saved. A value
|
|
168
|
+
# this SDK predates comes through unchanged.
|
|
169
|
+
class VoiceAgentConnection
|
|
170
|
+
SIP_TRANSPORTS = %w[auto udp tcp tls].freeze
|
|
171
|
+
SIP_MEDIA_ENCRYPTION = %w[disable allow require].freeze
|
|
172
|
+
WEBSOCKET_AUDIO_FORMATS = %w[pcm16_16000 pcm16_24000 pcm16_8000 mulaw_8000].freeze
|
|
173
|
+
|
|
174
|
+
attr_reader :base_url, :model, :header_names, :has_api_key,
|
|
175
|
+
:uri, :transport, :media_encryption, :username, :has_password, :headers,
|
|
176
|
+
:url, :audio_format, :has_auth_token, :custom_parameters
|
|
177
|
+
|
|
178
|
+
# @return [Hash] The raw parsed connection
|
|
179
|
+
attr_reader :raw
|
|
180
|
+
|
|
181
|
+
def initialize(data)
|
|
182
|
+
data ||= {}
|
|
183
|
+
@raw = data
|
|
184
|
+
@base_url = data["baseUrl"] || data["base_url"]
|
|
185
|
+
@model = data["model"]
|
|
186
|
+
@header_names = data["headerNames"] || data["header_names"]
|
|
187
|
+
@has_api_key = data.key?("hasApiKey") ? data["hasApiKey"] : data["has_api_key"]
|
|
188
|
+
@uri = data["uri"]
|
|
189
|
+
@transport = data["transport"]
|
|
190
|
+
@media_encryption = data["mediaEncryption"] || data["media_encryption"]
|
|
191
|
+
@username = data["username"]
|
|
192
|
+
@has_password = data.key?("hasPassword") ? data["hasPassword"] : data["has_password"]
|
|
193
|
+
@headers = data["headers"]
|
|
194
|
+
@url = data["url"]
|
|
195
|
+
@audio_format = data["audioFormat"] || data["audio_format"]
|
|
196
|
+
@has_auth_token = data.key?("hasAuthToken") ? data["hasAuthToken"] : data["has_auth_token"]
|
|
197
|
+
@custom_parameters = data["customParameters"] || data["custom_parameters"]
|
|
198
|
+
end
|
|
199
|
+
|
|
200
|
+
def to_h
|
|
201
|
+
{
|
|
202
|
+
base_url: base_url, model: model, header_names: header_names, has_api_key: has_api_key,
|
|
203
|
+
uri: uri, transport: transport, media_encryption: media_encryption, username: username,
|
|
204
|
+
has_password: has_password, headers: headers, url: url, audio_format: audio_format,
|
|
205
|
+
has_auth_token: has_auth_token, custom_parameters: custom_parameters
|
|
206
|
+
}.compact
|
|
207
|
+
end
|
|
208
|
+
end
|
|
209
|
+
|
|
151
210
|
# An AI agent that answers and places phone calls.
|
|
152
211
|
#
|
|
153
212
|
# +voice+ is a voice id from {VoiceVoicesResource#list} and +voice_label+
|
|
@@ -156,10 +215,27 @@ module Sendly
|
|
|
156
215
|
# which +tools.send_sms+ needs to actually send. +calls_handled+ and
|
|
157
216
|
# +avg_duration_secs+ are the agent's call stats. Timestamps are ISO 8601
|
|
158
217
|
# strings.
|
|
218
|
+
#
|
|
219
|
+
# +kind+ says who answers (see {KINDS}): "sendly" writes the replies from
|
|
220
|
+
# the agent's +instructions+; "custom_llm" listens and speaks while your
|
|
221
|
+
# chat completions endpoint writes each reply; "sip" connects the caller to
|
|
222
|
+
# your SIP address; "websocket" streams the call audio to your wss://
|
|
223
|
+
# server. A kind this SDK predates comes through unchanged. +connection+
|
|
224
|
+
# is how Sendly reaches your own agent ({VoiceAgentConnection}), +nil+ for
|
|
225
|
+
# a "sendly" agent. +has_signing_secret+ is true for your own agents:
|
|
226
|
+
# Sendly signs every request to them with that secret
|
|
227
|
+
# (+X-Sendly-Signature: t=<unix>,v1=<hex HMAC-SHA256>+).
|
|
228
|
+
# +signing_secret+ is the secret itself, set only on the response that
|
|
229
|
+
# just made it (creating your own agent, switching to one, or
|
|
230
|
+
# +rotate_signing_secret: true+) and +nil+ on every other read. Save it
|
|
231
|
+
# then; it is never shown again.
|
|
159
232
|
class VoiceAgent
|
|
233
|
+
KINDS = %w[sendly custom_llm sip websocket].freeze
|
|
234
|
+
|
|
160
235
|
attr_reader :id, :object, :name, :enabled, :voice, :voice_label, :language,
|
|
161
236
|
:greeting, :instructions, :tools, :can_send_sms, :calls_handled,
|
|
162
|
-
:avg_duration_secs, :created_at, :updated_at
|
|
237
|
+
:avg_duration_secs, :created_at, :updated_at, :kind, :connection,
|
|
238
|
+
:has_signing_secret, :signing_secret
|
|
163
239
|
|
|
164
240
|
# @return [Hash] The raw parsed response
|
|
165
241
|
attr_reader :raw
|
|
@@ -176,6 +252,11 @@ module Sendly
|
|
|
176
252
|
@language = data["language"]
|
|
177
253
|
@greeting = data["greeting"]
|
|
178
254
|
@instructions = data["instructions"]
|
|
255
|
+
@kind = data["kind"]
|
|
256
|
+
connection = data["connection"]
|
|
257
|
+
@connection = connection.is_a?(Hash) ? VoiceAgentConnection.new(connection) : nil
|
|
258
|
+
@has_signing_secret = data.key?("hasSigningSecret") ? data["hasSigningSecret"] : data["has_signing_secret"]
|
|
259
|
+
@signing_secret = data["signingSecret"] || data["signing_secret"]
|
|
179
260
|
@tools = VoiceAgentTools.new(data["tools"])
|
|
180
261
|
@can_send_sms = data.key?("canSendSms") ? data["canSendSms"] : data["can_send_sms"]
|
|
181
262
|
@calls_handled = data["callsHandled"] || data["calls_handled"] || 0
|
|
@@ -195,11 +276,17 @@ module Sendly
|
|
|
195
276
|
can_send_sms == true
|
|
196
277
|
end
|
|
197
278
|
|
|
279
|
+
# @return [Boolean] Whether the agent has a signing secret
|
|
280
|
+
def has_signing_secret?
|
|
281
|
+
has_signing_secret == true
|
|
282
|
+
end
|
|
283
|
+
|
|
198
284
|
def to_h
|
|
199
285
|
{
|
|
200
286
|
id: id, object: object, name: name, enabled: enabled, voice: voice,
|
|
201
287
|
voice_label: voice_label, language: language, greeting: greeting,
|
|
202
|
-
instructions: instructions,
|
|
288
|
+
instructions: instructions, kind: kind, connection: connection&.to_h,
|
|
289
|
+
has_signing_secret: has_signing_secret, tools: tools.to_h, can_send_sms: can_send_sms,
|
|
203
290
|
calls_handled: calls_handled, avg_duration_secs: avg_duration_secs,
|
|
204
291
|
created_at: created_at, updated_at: updated_at
|
|
205
292
|
}.compact
|
|
@@ -243,6 +330,89 @@ module Sendly
|
|
|
243
330
|
end
|
|
244
331
|
end
|
|
245
332
|
|
|
333
|
+
# One step of a connection test. +step+ is one of {STEPS}: "address" (the
|
|
334
|
+
# host resolved to a public address), "connect" (a connection opened),
|
|
335
|
+
# "login" (the SIP server accepted the credentials) or "reply" (the agent
|
|
336
|
+
# answered as it should). A step this SDK predates comes through
|
|
337
|
+
# unchanged. +detail+ says what happened at this step, in plain words.
|
|
338
|
+
class VoiceAgentTestStep
|
|
339
|
+
STEPS = %w[address connect login reply].freeze
|
|
340
|
+
|
|
341
|
+
attr_reader :step, :ok, :detail
|
|
342
|
+
|
|
343
|
+
def initialize(data)
|
|
344
|
+
data ||= {}
|
|
345
|
+
@step = data["step"]
|
|
346
|
+
@ok = data["ok"] == true
|
|
347
|
+
@detail = data["detail"]
|
|
348
|
+
end
|
|
349
|
+
|
|
350
|
+
# @return [Boolean] Whether this step worked
|
|
351
|
+
def ok?
|
|
352
|
+
ok
|
|
353
|
+
end
|
|
354
|
+
|
|
355
|
+
def to_h
|
|
356
|
+
{ step: step, ok: ok, detail: detail }.compact
|
|
357
|
+
end
|
|
358
|
+
end
|
|
359
|
+
|
|
360
|
+
# What {VoiceAgentsResource#test} found. A failed test is still a
|
|
361
|
+
# successful request: check {#ok?}.
|
|
362
|
+
#
|
|
363
|
+
# +outcome+ is one of {OUTCOMES}: "ok", or why not: "blocked_destination"
|
|
364
|
+
# (the host isn't a public address), "unreachable", "timeout",
|
|
365
|
+
# "tls_failed", "auth_required" (the SIP server wants credentials the agent
|
|
366
|
+
# doesn't have), "auth_failed" (the key, token or credentials were
|
|
367
|
+
# refused), "not_found" (wrong path or SIP user), "rejected" (any other
|
|
368
|
+
# refusal) or "bad_reply" (an answer outside the protocol). An outcome this
|
|
369
|
+
# SDK predates comes through unchanged. +message+ is one or two sentences
|
|
370
|
+
# to show a person: what happened and what to change. +status+ is the HTTP
|
|
371
|
+
# or SIP status the agent answered with, or +nil+; +latency_ms+ how long
|
|
372
|
+
# the agent took to answer, or +nil+. +signed+ is whether the request
|
|
373
|
+
# carried +X-Sendly-Signature+, as calls do (always false for "sip").
|
|
374
|
+
# +steps+ lists each step tried, in order, up to the first that failed.
|
|
375
|
+
class VoiceAgentTest
|
|
376
|
+
OUTCOMES = %w[
|
|
377
|
+
ok blocked_destination unreachable timeout tls_failed auth_required
|
|
378
|
+
auth_failed not_found rejected bad_reply
|
|
379
|
+
].freeze
|
|
380
|
+
|
|
381
|
+
attr_reader :ok, :outcome, :message, :status, :latency_ms, :signed, :steps
|
|
382
|
+
|
|
383
|
+
# @return [Hash] The raw parsed response
|
|
384
|
+
attr_reader :raw
|
|
385
|
+
|
|
386
|
+
def initialize(data)
|
|
387
|
+
data ||= {}
|
|
388
|
+
@raw = data
|
|
389
|
+
@ok = data["ok"] == true
|
|
390
|
+
@outcome = data["outcome"]
|
|
391
|
+
@message = data["message"]
|
|
392
|
+
@status = data["status"]
|
|
393
|
+
@latency_ms = data.key?("latencyMs") ? data["latencyMs"] : data["latency_ms"]
|
|
394
|
+
@signed = data["signed"] == true
|
|
395
|
+
@steps = (data["steps"] || []).map { |step| VoiceAgentTestStep.new(step) }
|
|
396
|
+
end
|
|
397
|
+
|
|
398
|
+
# @return [Boolean] Whether the agent answered the way a call needs
|
|
399
|
+
def ok?
|
|
400
|
+
ok
|
|
401
|
+
end
|
|
402
|
+
|
|
403
|
+
# @return [Boolean] Whether the request carried +X-Sendly-Signature+
|
|
404
|
+
def signed?
|
|
405
|
+
signed
|
|
406
|
+
end
|
|
407
|
+
|
|
408
|
+
def to_h
|
|
409
|
+
{
|
|
410
|
+
ok: ok, outcome: outcome, message: message, status: status,
|
|
411
|
+
latency_ms: latency_ms, signed: signed, steps: steps.map(&:to_h)
|
|
412
|
+
}
|
|
413
|
+
end
|
|
414
|
+
end
|
|
415
|
+
|
|
246
416
|
# The +data+ array a voice list method returns, as an Enumerable of
|
|
247
417
|
# model objects.
|
|
248
418
|
class VoiceDataList
|
|
@@ -300,6 +470,11 @@ module Sendly
|
|
|
300
470
|
module VoiceInput
|
|
301
471
|
OMIT = Object.new.freeze
|
|
302
472
|
TOOL_KEYS = { "send_sms" => "sendSms", "transfer_to" => "transferTo" }.freeze
|
|
473
|
+
CONNECTION_KEYS = {
|
|
474
|
+
"base_url" => "baseUrl", "api_key" => "apiKey", "media_encryption" => "mediaEncryption",
|
|
475
|
+
"audio_format" => "audioFormat", "auth_token" => "authToken",
|
|
476
|
+
"custom_parameters" => "customParameters"
|
|
477
|
+
}.freeze
|
|
303
478
|
|
|
304
479
|
module_function
|
|
305
480
|
|
|
@@ -323,7 +498,16 @@ module Sendly
|
|
|
323
498
|
tools.each_with_object({}) { |(key, value), out| out[TOOL_KEYS.fetch(key.to_s, key.to_s)] = value }
|
|
324
499
|
end
|
|
325
500
|
|
|
326
|
-
def
|
|
501
|
+
def connection_body(connection)
|
|
502
|
+
return connection unless connection.is_a?(Hash)
|
|
503
|
+
|
|
504
|
+
connection.each_with_object({}) do |(key, value), out|
|
|
505
|
+
out[CONNECTION_KEYS.fetch(key.to_s, key.to_s)] = value
|
|
506
|
+
end
|
|
507
|
+
end
|
|
508
|
+
|
|
509
|
+
def agent_body(name:, enabled:, voice:, language:, greeting:, instructions:, tools:,
|
|
510
|
+
kind: nil, connection: nil, rotate_signing_secret: nil)
|
|
327
511
|
body = {}
|
|
328
512
|
body[:name] = name unless name.nil?
|
|
329
513
|
body[:enabled] = enabled unless enabled.nil?
|
|
@@ -332,6 +516,9 @@ module Sendly
|
|
|
332
516
|
body[:greeting] = greeting unless greeting.nil?
|
|
333
517
|
body[:instructions] = instructions unless instructions.nil?
|
|
334
518
|
body[:tools] = tools_body(tools) unless tools.nil?
|
|
519
|
+
body[:kind] = kind unless kind.nil?
|
|
520
|
+
body[:connection] = connection_body(connection) unless connection.nil?
|
|
521
|
+
body[:rotateSigningSecret] = true if rotate_signing_secret == true
|
|
335
522
|
body
|
|
336
523
|
end
|
|
337
524
|
end
|
|
@@ -534,12 +721,37 @@ module Sendly
|
|
|
534
721
|
# @param tools [Hash, nil] +send_sms:+ and +transfer_to:+ (see
|
|
535
722
|
# {VoiceAgentTools}); camelCase keys are accepted too. +send_sms+
|
|
536
723
|
# defaults to +true+ and +transfer_to+ to +nil+.
|
|
724
|
+
# @param kind [String, nil] One of {VoiceAgent::KINDS}; the API defaults
|
|
725
|
+
# to "sendly". Any other kind is your own agent and needs the
|
|
726
|
+
# workspace's bring-your-own-agent feature, which support switches on.
|
|
727
|
+
# @param connection [Hash, nil] How Sendly reaches your own agent,
|
|
728
|
+
# matching +kind+; required for every kind but "sendly". snake_case or
|
|
729
|
+
# camelCase keys. "custom_llm": +base_url:+ (an https:// URL; Sendly
|
|
730
|
+
# sends +POST {base_url}/chat/completions+ with streaming on), +model:+,
|
|
731
|
+
# +api_key:+ (sent as +Authorization: Bearer+) and +headers:+ (up to 10
|
|
732
|
+
# extra headers with secret values). "sip": +uri:+ (+sip:+ or +sips:+
|
|
733
|
+
# with a user part and a hostname), +transport:+ (one of
|
|
734
|
+
# {VoiceAgentConnection::SIP_TRANSPORTS}, default "tcp"),
|
|
735
|
+
# +media_encryption:+ (one of {VoiceAgentConnection::SIP_MEDIA_ENCRYPTION},
|
|
736
|
+
# default "allow"), +username:+, +password:+ and +headers:+ (up to 10
|
|
737
|
+
# named +X-...+). "websocket": +url:+ (a wss:// URL), +audio_format:+ (one
|
|
738
|
+
# of {VoiceAgentConnection::WEBSOCKET_AUDIO_FORMATS}, default
|
|
739
|
+
# "pcm16_16000"), +auth_token:+ (sent as +Authorization: Bearer+) and
|
|
740
|
+
# +custom_parameters:+ (up to 20 strings sent in the +start+ message).
|
|
741
|
+
# It is sent as given: a key you leave out is not sent and +nil+ is sent
|
|
742
|
+
# as null. Hosts must resolve to public internet addresses.
|
|
537
743
|
# @param idempotency_key [String, nil] Idempotency key for this operation
|
|
538
|
-
# @return [Sendly::VoiceAgent] The new agent
|
|
744
|
+
# @return [Sendly::VoiceAgent] The new agent. For your own agent,
|
|
745
|
+
# +signing_secret+ carries its signing secret: save it now, it is never
|
|
746
|
+
# shown again.
|
|
539
747
|
# @raise [Sendly::ValidationError] If +name+ is blank, or HTTP 400
|
|
540
|
-
# +invalid_request+ naming the field the API rejected
|
|
748
|
+
# +invalid_request+ naming the field the API rejected (for a
|
|
749
|
+
# +connection+ that is missing or breaks a rule, the message reads
|
|
750
|
+
# +connection.<field>: <reason>+)
|
|
541
751
|
# @raise [Sendly::APIError] HTTP 409 +agent_limit+ when the workspace
|
|
542
|
-
# already has 20 agents, 403 +
|
|
752
|
+
# already has 20 agents, 403 +byo_agents_not_enabled+ (a +kind+ other
|
|
753
|
+
# than "sendly" while the workspace's bring-your-own-agent feature is
|
|
754
|
+
# off) / +forbidden+ / +live_key_required+
|
|
543
755
|
#
|
|
544
756
|
# @example
|
|
545
757
|
# agent = client.voice.agents.create(
|
|
@@ -550,13 +762,22 @@ module Sendly
|
|
|
550
762
|
# tools: { send_sms: true }
|
|
551
763
|
# )
|
|
552
764
|
# puts agent.id
|
|
765
|
+
#
|
|
766
|
+
# @example Answer with your own WebSocket server
|
|
767
|
+
# agent = client.voice.agents.create(
|
|
768
|
+
# name: "Support line",
|
|
769
|
+
# kind: "websocket",
|
|
770
|
+
# connection: { url: "wss://agent.example.com/calls", auth_token: "tok_123" }
|
|
771
|
+
# )
|
|
772
|
+
# secret = agent.signing_secret # shown only now
|
|
553
773
|
def create(name:, enabled: nil, voice: nil, language: nil, greeting: nil, instructions: nil,
|
|
554
|
-
tools: nil, idempotency_key: nil)
|
|
774
|
+
tools: nil, kind: nil, connection: nil, idempotency_key: nil)
|
|
555
775
|
VoiceInput.require_text!(name, "name is required")
|
|
556
776
|
|
|
557
777
|
body = VoiceInput.agent_body(
|
|
558
778
|
name: name, enabled: enabled, voice: voice, language: language,
|
|
559
|
-
greeting: greeting, instructions: instructions, tools: tools
|
|
779
|
+
greeting: greeting, instructions: instructions, tools: tools,
|
|
780
|
+
kind: kind, connection: connection
|
|
560
781
|
)
|
|
561
782
|
response = @client.post("/voice/agents", body, idempotency_key: idempotency_key)
|
|
562
783
|
VoiceAgent.new(response)
|
|
@@ -582,6 +803,13 @@ module Sendly
|
|
|
582
803
|
# team workspace, also a role that can manage API keys. Pass only what
|
|
583
804
|
# changes; +tools+ keys you leave out keep their current values.
|
|
584
805
|
#
|
|
806
|
+
# With the same +kind+, +connection+ is merged into the saved one: keys
|
|
807
|
+
# you leave out keep their values. Changing +kind+ to one of your own
|
|
808
|
+
# needs that kind's +connection+. Switching a "sendly" agent to one of
|
|
809
|
+
# your own kinds makes a signing secret, returned once in
|
|
810
|
+
# +signing_secret+; switching back to "sendly" removes the connection and
|
|
811
|
+
# the signing secret.
|
|
812
|
+
#
|
|
585
813
|
# @param id [String] Agent identifier
|
|
586
814
|
# @param name [String, nil] 1-80 characters
|
|
587
815
|
# @param enabled [Boolean, nil] Switch the agent on or off
|
|
@@ -593,11 +821,22 @@ module Sendly
|
|
|
593
821
|
# @param instructions [String, nil] Up to 4000 characters; +""+ clears it
|
|
594
822
|
# @param tools [Hash, nil] Tool settings to change (+send_sms:+,
|
|
595
823
|
# +transfer_to:+); +transfer_to: nil+ clears the number
|
|
824
|
+
# @param kind [String, nil] One of {VoiceAgent::KINDS}
|
|
825
|
+
# @param connection [Hash, nil] Connection fields to change (see
|
|
826
|
+
# {#create}); a secret you leave out keeps its saved value and +nil+
|
|
827
|
+
# removes it
|
|
828
|
+
# @param rotate_signing_secret [Boolean, nil] +true+ makes a new signing
|
|
829
|
+
# secret for your own agent, returned once in +signing_secret+ (save it
|
|
830
|
+
# now; it is never shown again). The old secret stops working at once.
|
|
831
|
+
# Only +true+ is sent.
|
|
596
832
|
# @param idempotency_key [String, nil] Idempotency key for this operation
|
|
597
833
|
# @return [Sendly::VoiceAgent] The agent after the change
|
|
598
834
|
# @raise [Sendly::ValidationError] If +id+ is blank, or HTTP 400
|
|
599
|
-
# +invalid_request+ naming the field the API rejected
|
|
835
|
+
# +invalid_request+ naming the field the API rejected (also a
|
|
836
|
+
# +connection+ that breaks a rule or is missing when +kind+ changes, or
|
|
837
|
+
# +rotate_signing_secret+ on a "sendly" agent)
|
|
600
838
|
# @raise [Sendly::NotFoundError] HTTP 404 +agent_not_found+
|
|
839
|
+
# @raise [Sendly::APIError] HTTP 403 +byo_agents_not_enabled+
|
|
601
840
|
#
|
|
602
841
|
# @example
|
|
603
842
|
# client.voice.agents.update(
|
|
@@ -605,18 +844,75 @@ module Sendly
|
|
|
605
844
|
# greeting: "Thanks for calling Acme. How can I help today?",
|
|
606
845
|
# tools: { send_sms: false }
|
|
607
846
|
# )
|
|
847
|
+
#
|
|
848
|
+
# @example Rotate your own agent's signing secret
|
|
849
|
+
# secret = client.voice.agents.update(agent.id, rotate_signing_secret: true).signing_secret
|
|
608
850
|
def update(id, name: nil, enabled: nil, voice: nil, language: nil, greeting: nil, instructions: nil,
|
|
609
|
-
tools: nil, idempotency_key: nil)
|
|
851
|
+
tools: nil, kind: nil, connection: nil, rotate_signing_secret: nil, idempotency_key: nil)
|
|
610
852
|
path = VoiceInput.agent_path(id)
|
|
611
853
|
body = VoiceInput.agent_body(
|
|
612
854
|
name: name, enabled: enabled, voice: voice, language: language,
|
|
613
|
-
greeting: greeting, instructions: instructions, tools: tools
|
|
855
|
+
greeting: greeting, instructions: instructions, tools: tools,
|
|
856
|
+
kind: kind, connection: connection, rotate_signing_secret: rotate_signing_secret
|
|
614
857
|
)
|
|
615
858
|
|
|
616
859
|
response = @client.patch(path, body, idempotency_key: idempotency_key)
|
|
617
860
|
VoiceAgent.new(response)
|
|
618
861
|
end
|
|
619
862
|
|
|
863
|
+
# Test your own agent's connection the way a call would reach it,
|
|
864
|
+
# without placing one. Requires the +calls:write+ scope and a live key.
|
|
865
|
+
#
|
|
866
|
+
# "custom_llm" gets a signed, streamed chat completion with a test
|
|
867
|
+
# message. "websocket" gets a signed connection with +connected+, a
|
|
868
|
+
# +start+ carrying +test: true+, half a second of silence and a +stop+
|
|
869
|
+
# with reason +test_finished+. "sip" gets an +OPTIONS+ request, answered
|
|
870
|
+
# with the saved credentials if the server asks; a SIP server answering
|
|
871
|
+
# shows the address and credentials work, not which agent picks up.
|
|
872
|
+
#
|
|
873
|
+
# Pass +connection+ to test settings before saving them. A workspace can
|
|
874
|
+
# run 10 tests a minute. No Idempotency-Key is sent.
|
|
875
|
+
#
|
|
876
|
+
# @param id [String] Agent identifier
|
|
877
|
+
# @param kind [String, nil] "custom_llm", "sip" or "websocket": the kind
|
|
878
|
+
# of the settings in +connection+. Defaults to the agent's own kind.
|
|
879
|
+
# Needed to test settings of another kind, such as on a "sendly" agent
|
|
880
|
+
# before switching it.
|
|
881
|
+
# @param connection [Hash, nil] Settings to test instead of the saved
|
|
882
|
+
# ones, in the same shape as on {#create}. Nothing is saved. For the
|
|
883
|
+
# agent's own kind, a secret left out is taken from the saved
|
|
884
|
+
# connection, while the host stays the same.
|
|
885
|
+
# @param instructions [String, nil] For "custom_llm": the system prompt to
|
|
886
|
+
# send, up to 4000 characters. Defaults to the agent's instructions.
|
|
887
|
+
# @return [Sendly::VoiceAgentTest] What the test found; check +ok?+
|
|
888
|
+
# @raise [Sendly::ValidationError] If +id+ is blank, or HTTP 400
|
|
889
|
+
# +invalid_request+ (a "sendly" agent and no +kind+, or a +connection+
|
|
890
|
+
# that breaks a rule)
|
|
891
|
+
# @raise [Sendly::NotFoundError] HTTP 404 +agent_not_found+
|
|
892
|
+
# @raise [Sendly::RateLimitError] HTTP 429 after 10 tests in a minute
|
|
893
|
+
# @raise [Sendly::APIError] HTTP 403 +byo_agents_not_enabled+ /
|
|
894
|
+
# +live_key_required+
|
|
895
|
+
#
|
|
896
|
+
# @example
|
|
897
|
+
# result = client.voice.agents.test("3c4d5e6f-7081-4293-a4b5-c6d7e8f90a1b")
|
|
898
|
+
# puts "#{result.outcome}: #{result.message}" unless result.ok?
|
|
899
|
+
#
|
|
900
|
+
# @example Try a new address before saving it
|
|
901
|
+
# client.voice.agents.test(
|
|
902
|
+
# "3c4d5e6f-7081-4293-a4b5-c6d7e8f90a1b",
|
|
903
|
+
# connection: { uri: "sip:+15125550100@sip.example.com", transport: "tls" }
|
|
904
|
+
# )
|
|
905
|
+
def test(id, kind: nil, connection: nil, instructions: nil)
|
|
906
|
+
path = "#{VoiceInput.agent_path(id)}/test"
|
|
907
|
+
body = {}
|
|
908
|
+
body[:kind] = kind unless kind.nil?
|
|
909
|
+
body[:connection] = VoiceInput.connection_body(connection) unless connection.nil?
|
|
910
|
+
body[:instructions] = instructions unless instructions.nil?
|
|
911
|
+
|
|
912
|
+
response = @client.post(path, body, auto_idempotency_key: false)
|
|
913
|
+
VoiceAgentTest.new(response)
|
|
914
|
+
end
|
|
915
|
+
|
|
620
916
|
# Delete an agent and revoke its sending key. Requires the +calls:write+
|
|
621
917
|
# scope and a live key; in a team workspace, also a role that can manage
|
|
622
918
|
# API keys.
|
|
@@ -689,7 +985,8 @@ module Sendly
|
|
|
689
985
|
# +agent_required+, +invalid_address+ (400 and 422) and
|
|
690
986
|
# +e911_not_applicable+; {Sendly::APIError} with the HTTP status for
|
|
691
987
|
# +agent_disabled+ / +agent_limit+ / +agent_in_use+ (409) and +forbidden+
|
|
692
|
-
# / +live_key_required+ / +insufficient_permissions+
|
|
988
|
+
# / +live_key_required+ / +insufficient_permissions+ /
|
|
989
|
+
# +byo_agents_not_enabled+ (403); and
|
|
693
990
|
# {Sendly::ServerError} (not an +APIError+) for +voice_attach_failed+ /
|
|
694
991
|
# +carrier_refused+ / +voice_unavailable+ (503) and
|
|
695
992
|
# +voice_internal_error+ (500). Every API error keeps the parsed body on
|
|
@@ -168,6 +168,26 @@ module Sendly
|
|
|
168
168
|
@client.post("/webhooks/#{URI.encode_www_form_component(webhook_id)}/backfill", body)
|
|
169
169
|
end
|
|
170
170
|
|
|
171
|
+
# Preview a recovery: count what {#redeliver} and {#backfill} would send
|
|
172
|
+
# for a window, without sending anything. The window is at most 7 days.
|
|
173
|
+
#
|
|
174
|
+
# @param webhook_id [String] Webhook ID
|
|
175
|
+
# @param since [String, nil] ISO-8601, default now − 24h
|
|
176
|
+
# @param until_ [String, nil] ISO-8601, default now
|
|
177
|
+
# @param event_types [Array<String>, nil] Event types to count, sent
|
|
178
|
+
# comma-separated (default all)
|
|
179
|
+
# @return [Sendly::WebhookRecoveryPreview]
|
|
180
|
+
def recovery_preview(webhook_id, since: nil, until_: nil, event_types: nil)
|
|
181
|
+
validate_webhook_id!(webhook_id)
|
|
182
|
+
params = {}
|
|
183
|
+
params[:since] = since unless since.nil?
|
|
184
|
+
params[:until] = until_ unless until_.nil?
|
|
185
|
+
params[:event_types] = event_types.join(",") unless event_types.nil? || event_types.empty?
|
|
186
|
+
|
|
187
|
+
response = @client.get("/webhooks/#{URI.encode_www_form_component(webhook_id)}/recovery-preview", params)
|
|
188
|
+
WebhookRecoveryPreview.new(response)
|
|
189
|
+
end
|
|
190
|
+
|
|
171
191
|
# Rotate the webhook signing secret
|
|
172
192
|
#
|
|
173
193
|
# Deliveries are signed with the new secret as soon as this returns, and
|
|
@@ -574,6 +574,11 @@ module Sendly
|
|
|
574
574
|
# the number (at most 512 characters). Defaults to the account's
|
|
575
575
|
# existing sender display name, then its business name. Only with
|
|
576
576
|
# +business_account_id+.
|
|
577
|
+
# @param idempotency_key [String, nil] Idempotency key for this operation
|
|
578
|
+
# (1-255 printable ASCII characters). The client already sends one per
|
|
579
|
+
# call; pass your own to make a repeat after a restart, or after an
|
|
580
|
+
# error the client does not retry, return the first answer instead of
|
|
581
|
+
# starting another charged signup.
|
|
577
582
|
# @return [WhatsAppSignupSession]
|
|
578
583
|
# @raise [Sendly::ServerError] +whatsapp_unavailable+ (503) while
|
|
579
584
|
# WhatsApp connections are unavailable. Nothing is charged. Only
|
|
@@ -617,7 +622,8 @@ module Sendly
|
|
|
617
622
|
# business_account_id: "102290129340398"
|
|
618
623
|
# )
|
|
619
624
|
# puts signup.status # "verifying"
|
|
620
|
-
def create(phone_number:, business_account_id: nil, verification_method: nil, display_name: nil
|
|
625
|
+
def create(phone_number:, business_account_id: nil, verification_method: nil, display_name: nil,
|
|
626
|
+
idempotency_key: nil)
|
|
621
627
|
raise ValidationError, "phone_number is required" if phone_number.nil? || phone_number.to_s.empty?
|
|
622
628
|
if !business_account_id.nil? && business_account_id.to_s.strip.empty?
|
|
623
629
|
raise ValidationError, "business_account_id must be a non-empty string"
|
|
@@ -629,7 +635,8 @@ module Sendly
|
|
|
629
635
|
body[:displayName] = display_name unless display_name.nil?
|
|
630
636
|
|
|
631
637
|
by_code = !business_account_id.nil? && !business_account_id.to_s.empty?
|
|
632
|
-
response = @client.post("/whatsapp/signup", body,
|
|
638
|
+
response = @client.post("/whatsapp/signup", body, idempotency_key: idempotency_key,
|
|
639
|
+
retry_server_errors: !by_code)
|
|
633
640
|
WhatsAppSignupSession.new(response)
|
|
634
641
|
end
|
|
635
642
|
|
|
@@ -1039,6 +1046,10 @@ module Sendly
|
|
|
1039
1046
|
# @param examples [Hash, nil] Example values for body placeholders,
|
|
1040
1047
|
# keyed by placeholder number: { "1" => "Acme Inc", "2" => "#4821" }.
|
|
1041
1048
|
# Required when the body has variables.
|
|
1049
|
+
# @param idempotency_key [String, nil] Idempotency key for this operation
|
|
1050
|
+
# (1-255 printable ASCII characters). Repeating the call with the same
|
|
1051
|
+
# key within 24 hours returns the first answer instead of creating the
|
|
1052
|
+
# template again.
|
|
1042
1053
|
# @return [WhatsAppTemplate] The created template (status "PENDING"),
|
|
1043
1054
|
# with any submission warnings
|
|
1044
1055
|
# @raise [Sendly::NotFoundError] +whatsapp_sender_not_connected+ (404) if
|
|
@@ -1062,7 +1073,7 @@ module Sendly
|
|
|
1062
1073
|
# )
|
|
1063
1074
|
# puts template.status # "PENDING"
|
|
1064
1075
|
def create(sender:, name:, language:, category:, body:,
|
|
1065
|
-
header: nil, footer: nil, buttons: nil, examples: nil)
|
|
1076
|
+
header: nil, footer: nil, buttons: nil, examples: nil, idempotency_key: nil)
|
|
1066
1077
|
raise ValidationError, "sender is required" if sender.nil? || sender.to_s.empty?
|
|
1067
1078
|
raise ValidationError, "name is required" if name.nil? || name.to_s.empty?
|
|
1068
1079
|
raise ValidationError, "language is required" if language.nil? || language.to_s.empty?
|
|
@@ -1081,7 +1092,7 @@ module Sendly
|
|
|
1081
1092
|
payload[:buttons] = buttons if buttons
|
|
1082
1093
|
payload[:examples] = examples if examples
|
|
1083
1094
|
|
|
1084
|
-
response = @client.post("/whatsapp/templates", payload)
|
|
1095
|
+
response = @client.post("/whatsapp/templates", payload, idempotency_key: idempotency_key)
|
|
1085
1096
|
WhatsAppTemplate.new(response)
|
|
1086
1097
|
end
|
|
1087
1098
|
|
|
@@ -1097,9 +1108,11 @@ module Sendly
|
|
|
1097
1108
|
# @param id [String] The template's id
|
|
1098
1109
|
# @param body [String, nil] Replacement body text
|
|
1099
1110
|
# @param header [String, nil] Replacement text header; it can't contain
|
|
1100
|
-
# {{n}} variables (+template_header_variable_unsupported+)
|
|
1101
|
-
#
|
|
1102
|
-
# @param
|
|
1111
|
+
# {{n}} variables (+template_header_variable_unsupported+). Pass +""+
|
|
1112
|
+
# to remove the header
|
|
1113
|
+
# @param footer [String, nil] Replacement footer. Pass +""+ to remove it
|
|
1114
|
+
# @param buttons [Array<Hash>, nil] Replacement buttons. Pass +[]+ to
|
|
1115
|
+
# remove every button
|
|
1103
1116
|
# @param examples [Hash, nil] Replacement example values for body placeholders
|
|
1104
1117
|
# @return [WhatsAppTemplate] The updated template (status "PENDING")
|
|
1105
1118
|
# @raise [Sendly::NotFoundError] If no such template exists
|
data/lib/sendly.rb
CHANGED
|
@@ -27,6 +27,7 @@ require_relative "sendly/tendlc_resource"
|
|
|
27
27
|
require_relative "sendly/links_resource"
|
|
28
28
|
require_relative "sendly/whatsapp_resource"
|
|
29
29
|
require_relative "sendly/rcs_resource"
|
|
30
|
+
require_relative "sendly/short_codes_resource"
|
|
30
31
|
require_relative "sendly/calls_resource"
|
|
31
32
|
require_relative "sendly/voice_resource"
|
|
32
33
|
|
metadata
CHANGED
|
@@ -1,14 +1,14 @@
|
|
|
1
1
|
--- !ruby/object:Gem::Specification
|
|
2
2
|
name: sendly
|
|
3
3
|
version: !ruby/object:Gem::Version
|
|
4
|
-
version: 4.
|
|
4
|
+
version: 4.7.0
|
|
5
5
|
platform: ruby
|
|
6
6
|
authors:
|
|
7
7
|
- Sendly
|
|
8
8
|
autorequire:
|
|
9
9
|
bindir: exe
|
|
10
10
|
cert_chain: []
|
|
11
|
-
date: 2026-
|
|
11
|
+
date: 2026-11-13 00:00:00.000000000 Z
|
|
12
12
|
dependencies:
|
|
13
13
|
- !ruby/object:Gem::Dependency
|
|
14
14
|
name: faraday
|
|
@@ -141,6 +141,7 @@ files:
|
|
|
141
141
|
- lib/sendly/numbers_resource.rb
|
|
142
142
|
- lib/sendly/rcs_resource.rb
|
|
143
143
|
- lib/sendly/rules_resource.rb
|
|
144
|
+
- lib/sendly/short_codes_resource.rb
|
|
144
145
|
- lib/sendly/templates_resource.rb
|
|
145
146
|
- lib/sendly/tendlc_resource.rb
|
|
146
147
|
- lib/sendly/types.rb
|