Passing FROM to an outbound call is now not required, and instead sets the random flag (#288)

Author: dragonmantank

README.md

@@ -265,6 +265,10 @@ $outboundCall
 $response = $client->voice()->createOutboundCall($outboundCall);
 ```
 
+If you would like to have the system randomly pick a FROM number from the numbers linked to an application, you can
+leave off the second parameter to `\Vonage\Voice\OutboundCall`'s constructor, and the system will select a number
+at random for you.
+
 ### Building a call with NCCO Actions
 
 Full parameter lists for NCCO Actions can be found in the [Voice API Docs](https://developer.nexmo.com/voice/voice-api/ncco-reference).

src/Voice/Client.php

@@ -55,9 +55,14 @@ public function createOutboundCall(OutboundCall $call): Event
     {
         $json = [
             'to' => [$call->getTo()],
-            'from' => $call->getFrom(),
         ];
 
+        if ($call->getFrom()) {
+            $json['from'] = $call->getFrom();
+        } else {
+            $json['random_from_number'] = true;
+        }
+
         if (null !== $call->getAnswerWebhook()) {
             $json['answer_url'] = [$call->getAnswerWebhook()->getUrl()];
             $json['answer_method'] = $call->getAnswerWebhook()->getMethod();
@@ -86,7 +91,9 @@ public function createOutboundCall(OutboundCall $call): Event
 
         $event = $this->api->create($json);
         $event['to'] = $call->getTo()->getId();
-        $event['from'] = $call->getFrom()->getId();
+        if ($call->getFrom()) {
+            $event['from'] = $call->getFrom()->getId();
+        }
         $event['timestamp'] = (new DateTimeImmutable("now", new DateTimeZone("UTC")))->format(DATE_ATOM);
 
         return new Event($event);

src/Voice/OutboundCall.php

@@ -54,6 +54,13 @@ class OutboundCall
      */
     protected $ncco;
 
+    /**
+     * Whether or not to use random numbers linked on the application
+     *
+     * @var bool
+     */
+    protected $randomFrom = false;
+
     /**
      * Length of time Vonage will allow a phone number to ring before hanging up
      *
@@ -66,10 +73,23 @@ class OutboundCall
      */
     protected $to;
 
-    public function __construct(EndpointInterface $to, Phone $from)
+    /**
+     * Creates a new Outbound Call object
+     * If no `$from` parameter is passed, the system will use a random number
+     * that is linked to the application instead.
+     *
+     * @param EndpointInterface $to
+     * @param Phone|null $from
+     * @return void
+     */
+    public function __construct(EndpointInterface $to, Phone $from = null)
     {
         $this->to = $to;
         $this->from = $from;
+
+        if (!$from) {
+            $this->randomFrom = true;
+        }
     }
 
     public function getAnswerWebhook(): ?Webhook
@@ -82,7 +102,7 @@ public function getEventWebhook(): ?Webhook
         return $this->eventWebhook;
     }
 
-    public function getFrom(): Phone
+    public function getFrom(): ?Phone
     {
         return $this->from;
     }
@@ -175,4 +195,9 @@ public function setRingingTimer(int $timer): self
 
         return $this;
     }
+
+    public function getRandomFrom(): bool
+    {
+        return $this->randomFrom;
+    }
 }

src/Voice/Webhook/Event.php

@@ -108,7 +108,7 @@ class Event
      */
     public function __construct(array $event)
     {
-        $this->from = $event['from'];
+        $this->from = $event['from'] ?? null;
         $this->to = $event['to'];
         $this->uuid = $event['uuid'] ?? $event['call_uuid'];
         $this->conversationUuid = $event['conversation_uuid'];
@@ -150,7 +150,7 @@ public function getDirection(): string
         return $this->direction;
     }
 
-    public function getFrom(): string
+    public function getFrom(): ?string
     {
         return $this->from;
     }

test/Voice/ClientTest.php

@@ -110,6 +110,46 @@ public function testCanCreateOutboundCall(): void
         $this->assertEquals('2541d01c-253e-48be-a8e0-da4bbe4c3722', $callData->getConversationUuid());
     }
 
+    public function testCanCreateOutboundCallWithRandomFromNumber(): void
+    {
+        $payload = [
+            'to' => [
+                [
+                    'type' => 'phone',
+                    'number' => '15555555555'
+                ]
+            ],
+            'random_from_number' => true,
+            'answer_url' => ['http://domain.test/answer'],
+            'answer_method' => 'POST',
+            'event_url' => ['http://domain.test/event'],
+            'event_method' => 'POST',
+            'machine_detection' => 'hangup',
+            'length_timer' => '7200',
+            'ringing_timer' => '60',
+        ];
+
+        $this->vonageClient->send(Argument::that(function (RequestInterface $request) use ($payload) {
+            $this->assertRequestUrl('api.nexmo.com', '/v1/calls', 'POST', $request);
+            $this->assertRequestBodyIsJson(json_encode($payload), $request);
+
+            return true;
+        }))->willReturn($this->getResponse('create-outbound-call-success', 201));
+
+        $outboundCall = (new OutboundCall(new Phone('15555555555')))
+            ->setEventWebhook(new Webhook('http://domain.test/event'))
+            ->setAnswerWebhook(new Webhook('http://domain.test/answer'))
+            ->setRingingTimer((int)$payload['ringing_timer'])
+            ->setLengthTimer((int)$payload['length_timer'])
+            ->setMachineDetection(OutboundCall::MACHINE_HANGUP);
+        $callData = $this->voiceClient->createOutboundCall($outboundCall);
+
+        $this->assertEquals('e46fd8bd-504d-4044-9600-26dd18b41111', $callData->getUuid());
+        $this->assertEquals('started', $callData->getStatus());
+        $this->assertEquals('outbound', $callData->getDirection());
+        $this->assertEquals('2541d01c-253e-48be-a8e0-da4bbe4c3722', $callData->getConversationUuid());
+    }
+
     /**
      * @throws ClientExceptionInterface
      * @throws Client\Exception\Exception