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.
@@ -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 an E.164 number
129
- # for callers who need a person, or +nil+. Agents cannot transfer calls
130
- # yet and never dial or read out this number: while it is set, a caller
131
- # who asks for a person is told their message will be passed on, and the
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, tools: tools.to_h, can_send_sms: can_send_sms,
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 agent_body(name:, enabled:, voice:, language:, greeting:, instructions:, tools:)
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 +forbidden+ / +live_key_required+
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+ (403); and
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, retry_server_errors: !by_code)
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
- # @param footer [String, nil] Replacement footer
1102
- # @param buttons [Array<Hash>, nil] Replacement buttons
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.5.1
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-10-20 00:00:00.000000000 Z
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